Mercurial > molko

annotate doc/docs/dev/ownership.md @ 366:19782ea1cf4a

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