Mercurial > molko

annotate libmlk-core/mlk/core/alloc.h @ 602:7e168493f0bd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cmake: fix NLS required
author David Demelier <markand@malikania.fr>
date Thu, 10 Aug 2023 21:16:05 +0200
parents 6c911cbc1fd7
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 /*
509
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
2 * alloc.h -- memory allocators
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 *
445
773a082f0b91 misc: update copyright years
David Demelier <markand@malikania.fr>
parents: 442
diff changeset
4 * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr>
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 * Permission to use, copy, modify, and/or distribute this software for any
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 * purpose with or without fee is hereby granted, provided that the above
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 * copyright notice and this permission notice appear in all copies.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 */
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
18
366
19782ea1cf4a misc: start rebranding
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
19 #ifndef MLK_CORE_ALLOC_H
19782ea1cf4a misc: start rebranding
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
20 #define MLK_CORE_ALLOC_H
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
21
509
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
22 /**
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
23 * \file mlk/core/alloc.h
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
24 * \brief Memory allocators.
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
25 *
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
26 * This module provides function to dynamically allocate data on the heap.
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
27 *
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
28 * ## Synopsis
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
29 *
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
30 * Most of the Molko's Engine API does not allocate data except in very few
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
31 * cases, otherwise this module is used each time it is required.
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
32 *
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
33 * ## Pointer block
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
34 *
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
35 * Data allocated by this module isn't a simple pointer to the region data but
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
36 * a custom block data that holds the size of the element and the number of it.
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
37 * This has been designed in the sense that reallocating data is easier for the
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
38 * caller as it is not required to pass the data length along.
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
39 *
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
40 * An allocated blocks looks like this:
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
41 *
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
42 * | Type | Description |
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
43 * |-------------------|-----------------------------|
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
44 * | `size_t` | Number of items allocated |
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
45 * | `size_t` | Size of individual elements |
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
46 * | `unsigned char *` | User data |
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
47 *
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
48 * The structure is allocated using the [flexible array member][fam] to avoid
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
49 * allocating data twice.
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
50 *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
51 * ### Example: allocating three ints
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
52 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
53 * Use the ::mlk_alloc_new function to allocate three ints with uninitialized
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
54 * memory.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
55 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
56 * ```c
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
57 * int *ptr = mlk_alloc_new(3, sizeof (int));
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
58 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
59 * ptr[0] = 10;
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
60 * ptr[1] = 20;
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
61 * ptr[2] = 30;
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
62 * ```
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
63 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
64 * This generates the following blocks in memory.
509
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
65 *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
66 * ```
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
67 * +-----------------+----------------+------------------------+
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
68 * | What | Value | Description |
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
69 * +-----------------+----------------+------------------------+
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
70 * | size_t | 3 | Three `int` requested |
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
71 * | size_t | sizeof (int) | Size of one `int` |
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
72 * | unsigned char * | undefined | Content of user memory |
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
73 * +-----------------+----------------+------------------------+
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
74 * ```
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
75 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
76 * \warning The returned address is the `unsigned char *` so the user must
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
77 * never free this address directly.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
78 *
545
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
79 * If you use ::mlk_alloc_resize, the storage will be expanded/shrinked
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
80 * automatically without the need to pass the actual size of the array.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
81 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
82 * ```c
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
83 * ptr = mlk_alloc_renew(ptr, 6);
509
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
84 *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
85 * // Now ptr holds 6 ints.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
86 * //
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
87 * // ptr[0], ptr[1], ptr[2] are kept unchanged.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
88 * // ptr[3-5] are uninitialized.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
89 * ```
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
90 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
91 * The block now looks like this:
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
92 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
93 * ```
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
94 * +-----------------+----------------+------------------------+
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
95 * | What | Value | Description |
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
96 * +-----------------+----------------+------------------------+
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
97 * | size_t | 6 | Six `int` requested |
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
98 * | size_t | sizeof (int) | Size of one `int` |
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
99 * | unsigned char * | undefined | Content of user memory |
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
100 * +-----------------+----------------+------------------------+
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
101 * ```
509
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
102 *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
103 * Finally, free the result using ::mlk_alloc_free, DON'T free the pointer
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
104 * directly.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
105 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
106 * ```c
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
107 * mlk_alloc_free(ptr);
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
108 * ```
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
109 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
110 * ## Custom allocators
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
111 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
112 * The whole library uses allocators defined in this module when it needs to
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
113 * allocate data. By default, C standard `malloc`, `realloc` and `free` are
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
114 * used but they call ::mlk_panic in case of memory exhaustion.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
115 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
116 * Those functions can be overridden through the ::mlk_alloc_set function with a
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
117 * set of functions defined in the structure ::mlk_alloc_funcs.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
118 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
119 * When using custom allocators, it is recommended to call ::mlk_alloc_set as
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
120 * early as possible because it will also set internal libraries to use those.
509
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
121 *
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
122 * [fam]: https://en.wikipedia.org/wiki/Flexible_array_member
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
123 */
a11cd7ea3a37 core: doxygenize action
David Demelier <markand@malikania.fr>
parents: 462
diff changeset
124
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
125 #include <stddef.h>
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
126
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
127 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
128 * \struct mlk_alloc_funcs
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
129 * \brief Custom allocator
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
130 */
438
25a56ca53ac2 core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents: 433
diff changeset
131 struct mlk_alloc_funcs {
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
132 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
133 * (read-write)
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
134 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
135 * Allocate the number of bytes uninitialized.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
136 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
137 * \param size the number of bytes to allocate (always > 0)
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
138 * \return a pointer to the allocated memory or NULL on error
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
139 */
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
140 void *(*alloc)(size_t size);
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
141
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
142 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
143 * (read-write)
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
144 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
145 * Realloc the pointer with the new size.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
146 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
147 * \param ptr the pointer to reallocate (never NULL)
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
148 * \param size the new size (always > 0)
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
149 * \return a pointer to the allocated memory or NULL on error
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
150 */
298
196264679079 misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents: 292
diff changeset
151 void *(*realloc)(void *, size_t);
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
152
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
153 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
154 * (read-write)
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
155 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
156 * Free the pointer memory.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
157 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
158 * \param ptr the pointer to release
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
159 */
298
196264679079 misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents: 292
diff changeset
160 void (*free)(void *);
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
161 };
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
162
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
163 #if defined(__cplusplus)
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
164 extern "C" {
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
165 #endif
292
08ab73b32832 misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents: 269
diff changeset
166
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
167 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
168 * Replace the memory allocators.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
169 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
170 * The parameter funcs must be kept alive until the program ends or it is
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
171 * replaced with a new value.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
172 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
173 * \param funcs the new allocator or NULL to re-use the defaults
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
174 */
252
95c2c4a72410 core: add alloc_set to set SDL allocators as well
David Demelier <markand@malikania.fr>
parents: 243
diff changeset
175 void
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
176 mlk_alloc_set(const struct mlk_alloc_funcs *funcs);
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
177
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
178 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
179 * Allocates a block memory.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
180 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
181 * \param n the number of elements to allocate
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
182 * \param w the size of each individual element
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
183 * \return whatever the allocator returned
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
184 */
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
185 void *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
186 mlk_alloc_new(size_t n, size_t w);
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
187
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
188 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
189 * \copydoc mlk_alloc_new
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
190 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
191 * Similar to ::mlk_alloc_new but also ensure the data is zero initialized.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
192 */
227
befa2e855d3b core: reinterface the alloc module
David Demelier <markand@malikania.fr>
parents: 226
diff changeset
193 void *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
194 mlk_alloc_new0(size_t n, size_t w);
227
befa2e855d3b core: reinterface the alloc module
David Demelier <markand@malikania.fr>
parents: 226
diff changeset
195
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
196 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
197 * Reallocate a block memory.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
198 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
199 * \note In contrast to standard `realloc` function, it is NOT possible to pass
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
200 * a NULL pointer in this function because it needs to know the initial
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
201 * block memory size.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
202 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
203 * \pre ptr != NULL
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
204 * \pre n > 0
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
205 * \param ptr the pointer to reallocate
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
206 * \param n the new size
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
207 * \return whatever the allocator returned to rearrange the pointer memory
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
208 */
227
befa2e855d3b core: reinterface the alloc module
David Demelier <markand@malikania.fr>
parents: 226
diff changeset
209 void *
544
0ff9f4a5c364 core: rename mlk_alloc_renew to mlk_alloc_resize
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
210 mlk_alloc_resize(void *ptr, size_t n);
227
befa2e855d3b core: reinterface the alloc module
David Demelier <markand@malikania.fr>
parents: 226
diff changeset
211
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
212 /**
545
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
213 * \copydoc mlk_alloc_resize
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
214 *
545
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
215 * Similar to ::mlk_alloc_resize but also ensure expanded data is zero
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
216 * initialized.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
217 */
227
befa2e855d3b core: reinterface the alloc module
David Demelier <markand@malikania.fr>
parents: 226
diff changeset
218 void *
544
0ff9f4a5c364 core: rename mlk_alloc_renew to mlk_alloc_resize
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
219 mlk_alloc_resize0(void *ptr, size_t n);
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
220
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
221 /**
545
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
222 * Similar to ::mlk_alloc_resize but expands the storage by n.
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
223 *
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
224 * Example, if the current pointer holds 10 `int`, passing 90 as n argument
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
225 * will expand the memory to a total of 100 `int`.
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
226 *
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
227 * \pre ptr != NULL
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
228 * \param ptr the pointer to expand
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
229 * \param n the number of items to append
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
230 * \return whatever the allocator returned to rearrange the pointer memory
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
231 */
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
232 void *
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
233 mlk_alloc_expand(void *ptr, size_t n);
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
234
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
235 /**
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
236 * \copydoc mlk_alloc_expand
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
237 *
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
238 * Similar to ::mlk_alloc_expand but also ensure expanded data is zero
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
239 * initialized.
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
240 */
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
241 void *
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
242 mlk_alloc_expand0(void *ptr, size_t n);
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
243
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
244 /**
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
245 * Duplicate a memory block.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
246 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
247 * \pre ptr != NULL
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
248 * \param ptr the pointer to copy
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
249 * \param n the number of elements to allocate
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
250 * \param w the size of each individual element
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
251 * \return whatever the allocator returned
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
252 */
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
253 void *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
254 mlk_alloc_dup(const void *ptr, size_t n, size_t w);
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
255
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
256 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
257 * Duplicate a string.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
258 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
259 * \pre src != NULL
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
260 * \param src the string to duplicate
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
261 * \return whatever the allocator returned
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
262 */
269
9b758eb84556 core: add alloc_rearray0 function
David Demelier <markand@malikania.fr>
parents: 253
diff changeset
263 char *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
264 mlk_alloc_sdup(const char *src);
269
9b758eb84556 core: add alloc_rearray0 function
David Demelier <markand@malikania.fr>
parents: 253
diff changeset
265
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
266 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
267 * Duplicate a string using a printf(3) format.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
268 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
269 * \pre fmt != NULL
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
270 * \param fmt the printf(3) format string
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
271 * \return whatever the allocator returned
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
272 */
402
d3fa956cdaf0 core: add alloc_sdupf
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
273 char *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
274 mlk_alloc_sdupf(const char *fmt, ...);
402
d3fa956cdaf0 core: add alloc_sdupf
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
275
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
276 /**
545
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
277 * Get the number of items in ptr.
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
278 *
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
279 * \pre ptr != NULL
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
280 * \param ptr the pointer block
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
281 * \return how many number of elements ptr holds
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
282 */
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
283 size_t
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
284 mlk_alloc_getn(const void *ptr);
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
285
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
286 /**
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
287 * Get the element width in ptr.
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
288 *
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
289 * \pre ptr != NULL
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
290 * \param ptr the pointer block
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
291 * \return size of individual elements ptr holds
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
292 */
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
293 size_t
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
294 mlk_alloc_getw(const void *ptr);
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
295
27303e9402de core: introduce mlk_alloc_expand
David Demelier <markand@malikania.fr>
parents: 544
diff changeset
296 /**
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
297 * Free resources specified by pointer.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
298 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
299 * If pointer is null, function is no-op.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
300 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
301 * \param ptr the memory to release (maybe NULL)
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
302 */
404
7321511052f6 core: rework alloc module
David Demelier <markand@malikania.fr>
parents: 402
diff changeset
303 void
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
304 mlk_alloc_free(void *ptr);
404
7321511052f6 core: rework alloc module
David Demelier <markand@malikania.fr>
parents: 402
diff changeset
305
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
306 #if defined(__cplusplus)
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
307 }
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
308 #endif
292
08ab73b32832 misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents: 269
diff changeset
309
366
19782ea1cf4a misc: start rebranding
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
310 #endif /* !MLK_CORE_ALLOC_H */