Mercurial > molko

annotate libmlk-core/mlk/core/alloc.h @ 517:6e8f6640e05b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: use extern C manually
author David Demelier <markand@malikania.fr>
date Sat, 04 Mar 2023 14:23:59 +0100
parents 21d2c66f3521
children 0ff9f4a5c364
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 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
79 * If you use ::mlk_alloc_renew, the storage will be expanded/shrinked
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
438
25a56ca53ac2 core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents: 433
diff changeset
163 struct mlk_alloc_pool {
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents: 252
diff changeset
164 void *data;
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents: 252
diff changeset
165 size_t elemsize;
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents: 252
diff changeset
166 size_t size;
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents: 252
diff changeset
167 size_t capacity;
298
196264679079 misc: remove usage of bool
David Demelier <markand@malikania.fr>
parents: 292
diff changeset
168 void (*finalizer)(void *);
228
2734223d3daf core: add a alloc_pool module
David Demelier <markand@malikania.fr>
parents: 227
diff changeset
169 };
2734223d3daf core: add a alloc_pool module
David Demelier <markand@malikania.fr>
parents: 227
diff changeset
170
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
171 #if defined(__cplusplus)
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
172 extern "C" {
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
173 #endif
292
08ab73b32832 misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents: 269
diff changeset
174
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
175 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
176 * Replace the memory allocators.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
177 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
178 * 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
179 * replaced with a new value.
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 funcs the new allocator or NULL to re-use the defaults
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
182 */
252
95c2c4a72410 core: add alloc_set to set SDL allocators as well
David Demelier <markand@malikania.fr>
parents: 243
diff changeset
183 void
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
184 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
185
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
186 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
187 * Allocates a block memory.
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 * \param n the number of elements to allocate
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
190 * \param w the size of each individual element
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
191 * \return whatever the allocator returned
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
192 */
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
193 void *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
194 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
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 * \copydoc mlk_alloc_new
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 * 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
200 */
227
befa2e855d3b core: reinterface the alloc module
David Demelier <markand@malikania.fr>
parents: 226
diff changeset
201 void *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
202 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
203
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
204 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
205 * Reallocate a block memory.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
206 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
207 * \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
208 * 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
209 * block memory size.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
210 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
211 * \pre ptr != NULL
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
212 * \pre n > 0
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
213 * \param ptr the pointer to reallocate
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
214 * \param n the new size
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
215 * \return whatever the allocator returned to rearrange the pointer memory
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
216 */
227
befa2e855d3b core: reinterface the alloc module
David Demelier <markand@malikania.fr>
parents: 226
diff changeset
217 void *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
218 mlk_alloc_renew(void *ptr, size_t n);
227
befa2e855d3b core: reinterface the alloc module
David Demelier <markand@malikania.fr>
parents: 226
diff changeset
219
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
220 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
221 * \copydoc mlk_alloc_renew
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
222 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
223 * Similar to ::mlk_alloc_new but also ensure expanded data is zero
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
224 * initialized.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
225 */
227
befa2e855d3b core: reinterface the alloc module
David Demelier <markand@malikania.fr>
parents: 226
diff changeset
226 void *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
227 mlk_alloc_renew0(void *ptr, size_t n);
182
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
228
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
229 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
230 * Duplicate a memory block.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
231 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
232 * \pre ptr != NULL
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
233 * \param ptr the pointer to copy
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
234 * \param n the number of elements to allocate
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
235 * \param w the size of each individual element
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
236 * \return whatever the allocator returned
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
237 */
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
238 void *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
239 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
240
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
241 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
242 * Duplicate a string.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
243 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
244 * \pre src != NULL
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
245 * \param src the string to duplicate
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
246 * \return whatever the allocator returned
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
247 */
269
9b758eb84556 core: add alloc_rearray0 function
David Demelier <markand@malikania.fr>
parents: 253
diff changeset
248 char *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
249 mlk_alloc_sdup(const char *src);
269
9b758eb84556 core: add alloc_rearray0 function
David Demelier <markand@malikania.fr>
parents: 253
diff changeset
250
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
251 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
252 * Duplicate a string using a printf(3) format.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
253 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
254 * \pre fmt != NULL
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
255 * \param fmt the printf(3) format string
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
256 * \return whatever the allocator returned
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
257 */
402
d3fa956cdaf0 core: add alloc_sdupf
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
258 char *
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
259 mlk_alloc_sdupf(const char *fmt, ...);
402
d3fa956cdaf0 core: add alloc_sdupf
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
260
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
261 /**
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
262 * Free resources specified by pointer.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
263 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
264 * If pointer is null, function is no-op.
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
265 *
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
266 * \param ptr the memory to release (maybe NULL)
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
267 */
404
7321511052f6 core: rework alloc module
David Demelier <markand@malikania.fr>
parents: 402
diff changeset
268 void
510
21d2c66f3521 core: doxygenize alloc
David Demelier <markand@malikania.fr>
parents: 509
diff changeset
269 mlk_alloc_free(void *ptr);
404
7321511052f6 core: rework alloc module
David Demelier <markand@malikania.fr>
parents: 402
diff changeset
270
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents: 252
diff changeset
271 /* alloc_pool functions. */
404
7321511052f6 core: rework alloc module
David Demelier <markand@malikania.fr>
parents: 402
diff changeset
272 void
442
9c3b3935f0aa core: rework allocations
David Demelier <markand@malikania.fr>
parents: 438
diff changeset
273 mlk_alloc_pool_init(struct mlk_alloc_pool *, size_t, size_t , void (*)(void *));
228
2734223d3daf core: add a alloc_pool module
David Demelier <markand@malikania.fr>
parents: 227
diff changeset
274
2734223d3daf core: add a alloc_pool module
David Demelier <markand@malikania.fr>
parents: 227
diff changeset
275 void *
438
25a56ca53ac2 core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents: 433
diff changeset
276 mlk_alloc_pool_new(struct mlk_alloc_pool *);
228
2734223d3daf core: add a alloc_pool module
David Demelier <markand@malikania.fr>
parents: 227
diff changeset
277
237
1bf5bd306bb0 core: add alloc_pool_get function
David Demelier <markand@malikania.fr>
parents: 228
diff changeset
278 void *
438
25a56ca53ac2 core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents: 433
diff changeset
279 mlk_alloc_pool_get(const struct mlk_alloc_pool *, size_t);
237
1bf5bd306bb0 core: add alloc_pool_get function
David Demelier <markand@malikania.fr>
parents: 228
diff changeset
280
404
7321511052f6 core: rework alloc module
David Demelier <markand@malikania.fr>
parents: 402
diff changeset
281 void *
438
25a56ca53ac2 core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents: 433
diff changeset
282 mlk_alloc_pool_shrink(struct mlk_alloc_pool *);
404
7321511052f6 core: rework alloc module
David Demelier <markand@malikania.fr>
parents: 402
diff changeset
283
228
2734223d3daf core: add a alloc_pool module
David Demelier <markand@malikania.fr>
parents: 227
diff changeset
284 void
438
25a56ca53ac2 core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents: 433
diff changeset
285 mlk_alloc_pool_finish(struct mlk_alloc_pool *);
228
2734223d3daf core: add a alloc_pool module
David Demelier <markand@malikania.fr>
parents: 227
diff changeset
286
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
287 #if defined(__cplusplus)
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
288 }
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 510
diff changeset
289 #endif
292
08ab73b32832 misc: add extern "C" {} blocks for C++ friends
David Demelier <markand@malikania.fr>
parents: 269
diff changeset
290
366
19782ea1cf4a misc: start rebranding
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
291 #endif /* !MLK_CORE_ALLOC_H */