Mercurial > molko
view doxygen/page-howto-ownership.c @ 235:fb304a94a05c
rpg: prepare equipment
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 26 Nov 2020 18:00:45 +0100 |
parents | eb0a7ab71023 |
children |
line wrap: on
line source
/** * \page howto-ownership Howto: ownership and memory management * \tableofcontents * * How memory and ownership is used within Molko's Adventure API. * * # Synopsis * * In C, memory management can be a cumbersome issue and a major common complain * when it comes to leak. * * As such, the API itself does not use dynamic allocations in most of the case. * Instead it is kept to the user responsability to handle storage of data. In * that manner the code stays simpler, stronger and more flexible. The API * itself does not have to deal with memory management and deallocation, it only * expect data from user and work with that. * * You can imagine a situation with a DVD player and some movies on DVDs. You * have one DVD player where you put some DVDs inside but the DVD player never * make its own copy, it simply reads your disc and you get it back afterwards. * * Following this philosophy, the Molko's Adventure API for this scenario would * look like this: * * ```c * struct dvd_player player; * struct dvd dvd; * * dvd_open(&dvd, "/dev/sr0"); * * dvd_player_turn_on(); * dvd_player_insert(&player, &dvd); * dvd_player_play(&player); * dvd_player_turn_off(); * ``` * * # Memory handling * * ## Arrays * * Some modules in the API may require an array. Depending on the situation they * can be passed as parameter or are usually of a fixed reasonable size in * structures. * * They are always annotated with a macro to let the user flexibility over it if * necessary. * * Example, a player has a set of spells. * * ```c * #define PLAYER_SPELL_MAX (16) * * struct player { * struct spell *spells[PLAYER_SPELL_MAX]; * }; * ``` * * ## Strings * * When dealing with strings, they are almost always referenced and not copied * unless explicitly required. As such, no allocation/deallocation required * either. * * ```c * struct player { * const char *name; // Not allocated, no deallocation * ``` * * # Ownership * * Alongside the memory handling comes the ownership. Related to the DVD * scenario explained above, not having to *own* a resource within a structure * means no allocation/deallocation required. * * Also, since C does not have a scoped mechanism, all fields in structured are * publicly available and to avoid allocating them on the heap they are always * declared to the user even if they need internal data. * * As a documentation notice, fields are always annotated using (XYZ) prefix * with some symbols to indicate whether user is allowed to touch or not. * * The letter *X* defines the following restriction * * - `+`: The property is readable/editable by the user, * - `-`: The property is readable by the user, * - `*`: The property is not meant to be used directly by the user. * * The letter *Y* can be set to `&` in that case means it is only referenced * and is not an owned property (usually a non-owning pointer). Which means * user is responsible for deallocation if required. * * The finall letter *Z* can be set to `?` which means it is optional (like a * nullable pointer). * * Examples: * * ```c * struct foo { * int x; // (+) Position in x. * int y; // (+) Position in y. * struct theme *th; // (+&?) Theme to use. * unsigned int elapsed; // (-) Elapsed time since last frame. * struct texture text; // (*) Texture used for rendering. * }; * ``` * * Within this structure, the fields `x` and `y` are completely accessible to * the user for both reading/writing. The field `th` is an optional non-owning * pointer to a theme which is also readable/writable. The field `elapsed` is * readable but should not be modified. Finally, the field `text` is private * and should not be touched by the user. * * # Memory handling in Molko's Adventure API * * | | Dynamic allocation? | Notes | * |---------|---------------------|---------------------------------------------------------| * | libcore | None | The util.h provides convenient allocators for the user. | * | libui | None | | * | librpg | In map.h module | Maps are big chunk of data. | */