Mercurial > molko
annotate doxygen/page-howto-ownership.c @ 195:02285657294c
examples: fix drawable animation delay
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sat, 07 Nov 2020 21:08:47 +0100 |
parents | eb0a7ab71023 |
children |
rev | line source |
---|---|
169
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
1 /** |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
2 * \page howto-ownership Howto: ownership and memory management |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
3 * \tableofcontents |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
4 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
5 * How memory and ownership is used within Molko's Adventure API. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
6 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
7 * # Synopsis |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
8 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
9 * In C, memory management can be a cumbersome issue and a major common complain |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
10 * when it comes to leak. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
11 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
12 * As such, the API itself does not use dynamic allocations in most of the case. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
13 * Instead it is kept to the user responsability to handle storage of data. In |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
14 * that manner the code stays simpler, stronger and more flexible. The API |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
15 * itself does not have to deal with memory management and deallocation, it only |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
16 * expect data from user and work with that. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
17 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
18 * You can imagine a situation with a DVD player and some movies on DVDs. You |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
19 * have one DVD player where you put some DVDs inside but the DVD player never |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
20 * make its own copy, it simply reads your disc and you get it back afterwards. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
21 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
22 * Following this philosophy, the Molko's Adventure API for this scenario would |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
23 * look like this: |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
24 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
25 * ```c |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
26 * struct dvd_player player; |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
27 * struct dvd dvd; |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
28 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
29 * dvd_open(&dvd, "/dev/sr0"); |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
30 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
31 * dvd_player_turn_on(); |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
32 * dvd_player_insert(&player, &dvd); |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
33 * dvd_player_play(&player); |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
34 * dvd_player_turn_off(); |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
35 * ``` |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
36 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
37 * # Memory handling |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
38 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
39 * ## Arrays |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
40 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
41 * Some modules in the API may require an array. Depending on the situation they |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
42 * can be passed as parameter or are usually of a fixed reasonable size in |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
43 * structures. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
44 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
45 * They are always annotated with a macro to let the user flexibility over it if |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
46 * necessary. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
47 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
48 * Example, a player has a set of spells. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
49 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
50 * ```c |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
51 * #define PLAYER_SPELL_MAX (16) |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
52 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
53 * struct player { |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
54 * struct spell *spells[PLAYER_SPELL_MAX]; |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
55 * }; |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
56 * ``` |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
57 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
58 * ## Strings |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
59 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
60 * When dealing with strings, they are almost always referenced and not copied |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
61 * unless explicitly required. As such, no allocation/deallocation required |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
62 * either. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
63 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
64 * ```c |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
65 * struct player { |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
66 * const char *name; // Not allocated, no deallocation |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
67 * ``` |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
68 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
69 * # Ownership |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
70 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
71 * Alongside the memory handling comes the ownership. Related to the DVD |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
72 * scenario explained above, not having to *own* a resource within a structure |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
73 * means no allocation/deallocation required. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
74 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
75 * Also, since C does not have a scoped mechanism, all fields in structured are |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
76 * publicly available and to avoid allocating them on the heap they are always |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
77 * declared to the user even if they need internal data. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
78 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
79 * As a documentation notice, fields are always annotated using (XYZ) prefix |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
80 * with some symbols to indicate whether user is allowed to touch or not. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
81 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
82 * The letter *X* defines the following restriction |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
83 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
84 * - `+`: The property is readable/editable by the user, |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
85 * - `-`: The property is readable by the user, |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
86 * - `*`: The property is not meant to be used directly by the user. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
87 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
88 * The letter *Y* can be set to `&` in that case means it is only referenced |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
89 * and is not an owned property (usually a non-owning pointer). Which means |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
90 * user is responsible for deallocation if required. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
91 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
92 * The finall letter *Z* can be set to `?` which means it is optional (like a |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
93 * nullable pointer). |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
94 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
95 * Examples: |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
96 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
97 * ```c |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
98 * struct foo { |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
99 * int x; // (+) Position in x. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
100 * int y; // (+) Position in y. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
101 * struct theme *th; // (+&?) Theme to use. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
102 * unsigned int elapsed; // (-) Elapsed time since last frame. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
103 * struct texture text; // (*) Texture used for rendering. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
104 * }; |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
105 * ``` |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
106 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
107 * Within this structure, the fields `x` and `y` are completely accessible to |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
108 * the user for both reading/writing. The field `th` is an optional non-owning |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
109 * pointer to a theme which is also readable/writable. The field `elapsed` is |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
110 * readable but should not be modified. Finally, the field `text` is private |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
111 * and should not be touched by the user. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
112 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
113 * # Memory handling in Molko's Adventure API |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
114 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
115 * | | Dynamic allocation? | Notes | |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
116 * |---------|---------------------|---------------------------------------------------------| |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
117 * | libcore | None | The util.h provides convenient allocators for the user. | |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
118 * | libui | None | | |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
119 * | librpg | In map.h module | Maps are big chunk of data. | |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
120 */ |