Mercurial > molko

annotate libcore/core/alloc.h @ 182:f6497ec74b49

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
core: add alloc module, closes #2512
author David Demelier <markand@malikania.fr>
date Tue, 27 Oct 2020 16:54:18 +0100
parents
children dd7c8d4321a3
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 /*
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 * alloc.h -- custom allocators
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 * Copyright (c) 2020 David Demelier <markand@malikania.fr>
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
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 #ifndef MOLKO_ALLOC_H
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 #define MOLKO_ALLOC_H
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
21
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 /**
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 * \file alloc.h
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 * \brief Custom allocators.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 * This module controls how the API should allocate memory. Although dynamic
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 * allocation isn't much used in the core API, it is used in few places where
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 * static arrays would not fit (e.g. loading maps).
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
29 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 * To change the allocator, simply modify the global allocator object.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 */
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
32
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 #include <stddef.h>
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
34
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 #include "util.h"
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
36
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 /**
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 * \brief Global allocator strategy.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 */
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 struct allocator {
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 /**
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 * (+) Allocate some data.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
44 * The default implementation uses malloc and calls \ref panic in case
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 * of failure.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 * \pre size != 0
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 * \param size the size to alloc
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 * \return A pointer to the allocated region (NULL is allowed).
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 */
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 void *(*alloc)(size_t size);
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
52
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 /**
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 * (+) Realloc a region.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 * The default implementation uses malloc and calls \ref panic in case
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 * of failure.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 * \pre size != 0
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 * \param ptr the old region
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 * \param size the new size
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 * \return A pointer to the allocated region (NULL is allowed).
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 */
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 void *(*realloc)(void *ptr, size_t size);
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
65
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 /**
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 * (+) Free resources.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 * The default implementation calls standard C free function.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 * \param ptr the region (may be NULL)
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 */
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
73 void (*free)(void *ptr);
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 };
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
75
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
76 /**
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 * \brief Global allocator object.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 */
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 extern struct allocator allocator;
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
80
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 /**
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 * Shortcut for allocator->alloc.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
84 * \pre n != 0 && size != 0
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 * \param n the number of objects to allocate
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 * \param size the size of each object
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 * \return The result of allocator->alloc.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 */
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 void *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 alloc(size_t n, size_t size) PLAT_NODISCARD;
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
91
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
92 /**
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
93 * Shortcut for allocator->alloc and then use memset to clear memory.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
94 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
95 * \pre n != 0 && size != 0
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 * \param n the number of objects to allocate
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 * \param size the size of each object
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
98 * \return The result of allocator->alloc.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
99 */
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
100 void *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 alloc_zero(size_t n, size_t size) PLAT_NODISCARD;
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
102
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 /**
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
104 * Duplicate region pointer by ptr.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
106 * This function calls \ref alloc to allocate memory.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
107 *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
108 * \pre ptr != NULL
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
109 * \param ptr the pointer
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 * \param size the size of the memory to copy
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 * \return The result of allocator->alloc filled with a copy of ptr.
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
112 */
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
113 void *
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
114 alloc_dup(const void *ptr, size_t size) PLAT_NODISCARD;
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
115
f6497ec74b49 core: add alloc module, closes #2512
David Demelier <markand@malikania.fr>
parents:
diff changeset
116 #endif /* !MOLKO_ALLOC_H */