Mercurial > molko
annotate man/mlk-alloc.3 @ 530:acc483db7bff
core: doxygenize mouse
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sat, 04 Mar 2023 20:21:37 +0100 |
parents | 9c3b3935f0aa |
children |
rev | line source |
---|---|
438
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
1 .Dd $Mdocdate$ |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
2 .Dt MLK-ALLOC 3 |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
3 .Os |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
4 .Sh NAME |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
5 .Nm mlk-alloc |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
6 .Nd allocation routines |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
7 .Sh LIBRARY |
442
9c3b3935f0aa
core: rework allocations
David Demelier <markand@malikania.fr>
parents:
438
diff
changeset
|
8 libmlk-core (-lmlk-core) |
438
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
9 .Sh SYNOPSIS |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
10 .In mlk/core/alloc.h |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
11 .Ft void * |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
12 .Fn mlk_alloc_dup "const void *ptr" "size_t size" |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
13 .Ft char * |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
14 .Fn mlk_alloc_sdup "const char *src" |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
15 .Ft char * |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
16 .Fn mlk_alloc_sdupf "const char *fmt" ... |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
17 .Ft void |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
18 .Fn mlk_alloc_free "void *ptr" |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
19 .Ft void |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
20 .Fn mlk_alloc_pool_init "struct mlk_alloc_pool *pool" "size_t elemsize" "void (*finalizer)(void *)" |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
21 .Ft void * |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
22 .Fn mlk_alloc_pool_new "struct mlk_alloc_pool *pool" |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
23 .Ft void * |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
24 .Fn mlk_alloc_pool_get "const struct mlk_alloc_pool *pool, size_t index" |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
25 .Ft void * |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
26 .Fn mlk_alloc_pool_shrink "struct mlk_alloc_pool *pool" |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
27 .Ft void |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
28 .Fn mlk_alloc_pool_finish "struct mlk_alloc_pool *pool" |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
29 .Sh DESCRIPTION |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
30 The allocation strategy in the mlk framework is to call |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
31 .Xr mlk-panic 3 |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
32 in case of memory exhaustion. It is designed in mind that recovering of lack of |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
33 memory in a game is usually impossible. However, the user can still change the |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
34 allocation functions to perform custom actions but it should be noted that mlk |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
35 framework don't except any of the function to return NULL in case of memory |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
36 exhaustion. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
37 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
38 The user should use its own functions when memory exhaustion has to be tested. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
39 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
40 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
41 .Vt "struct mlk_alloc_funcs" |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
42 type is defined as: |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
43 .Bd -literal |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
44 struct mlk_alloc_funcs { |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
45 void *(*alloc)(size_t size); |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
46 void *(*realloc)(void *ptr, size_t newsize); |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
47 void (*free)(void *ptr); |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
48 }; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
49 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
50 .Ed |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
51 Its fields are defined as following: |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
52 .Bl -tag |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
53 .It Va alloc |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
54 This function is called to allocate new memory, it takes the memory |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
55 .Fa size |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
56 as argument and must return a non-NULL value. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
57 .It Va realloc |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
58 This function must reallocate the memory region pointed by |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
59 .Fa ptr |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
60 with its new size given by |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
61 .Fa newsize . |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
62 The original |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
63 .Fa ptr |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
64 may be NULL. The function must not return a non-NULL value. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
65 .It Va free |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
66 This function must free the pointer specified by |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
67 .Fa ptr . |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
68 .El |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
69 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
70 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
71 .Vt "struct mlk_alloc_pool" |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
72 type is defined as: |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
73 .Bd -literal |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
74 struct mlk_alloc_pool { |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
75 void *data; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
76 size_t elemsize; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
77 size_t size; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
78 size_t capacity; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
79 void (*finalizer)(void *); |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
80 }; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
81 .Ed |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
82 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
83 Its fields are defined as following: |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
84 .Bl -tag |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
85 .It Va data |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
86 Pointer to the memory region. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
87 .It Va elemsize |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
88 Size of individual element. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
89 .It Va size |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
90 Number of items in array. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
91 .It Va capacity |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
92 Current capacity which may be greater or equal to |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
93 .Va size . |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
94 .It Va finalizer |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
95 Optional finalizer function that should finalize the object pointed by |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
96 .Va data |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
97 for every element. This function is only called when the |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
98 .Fn mlk_alloc_pool_finish |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
99 function is used. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
100 .El |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
101 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
102 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
103 .Fn mlk_alloc_dup |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
104 function duplicates the pointer |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
105 .Fa ptr |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
106 with the given |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
107 .Fa size . |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
108 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
109 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
110 .Fn mlk_alloc_sdup |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
111 function duplicates the string |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
112 .Fa src |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
113 and return it. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
114 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
115 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
116 .Fn mlk_alloc_sdupf |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
117 function creates a dynamically allocated string using printf(3) format like. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
118 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
119 the |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
120 .Fn mlk_alloc_free |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
121 function releases memory previously allocated. It must always be used instead of |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
122 C standard |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
123 .Xr free 3 |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
124 function if any function of this module was used to allocates the |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
125 .Fa ptr |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
126 memory region. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
127 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
128 The following functions can be used to increase a dynamically allocated array |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
129 automatically. It allocates twice as the current storage when size exceeds |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
130 capacity. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
131 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
132 It uses realloc mechanism to upgrade the new storage space so pointers returned |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
133 in |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
134 .Fn mlk_alloc_pool_new |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
135 may get invalided when this function is called. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
136 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
137 It is designed in mind to help allocating an array of elements when they can't |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
138 be determined at runtime (e.g. while reading a file) without the performance |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
139 cost of using |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
140 .Fn mlk_alloc_rearray |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
141 for every elements. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
142 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
143 The initial capacity is controlled by the |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
144 .Dv MLK_ALLOC_POOL_INIT_DEFAULT |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
145 macro and |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
146 .Em must |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
147 be a power of two. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
148 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
149 A custom finalizer function can be set to finalize each individual object if |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
150 necessary. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
151 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
152 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
153 .Fn mlk_alloc_pool_init |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
154 function initializes the |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
155 .Fa pool |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
156 as an array where elements have |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
157 .Fa elemsize |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
158 size. Optional |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
159 .Fa finalizer |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
160 argument can be passed to finalize every element when clearing the pool. This |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
161 will effectively create a initial storage according to |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
162 .Dv MLK_ALLOC_POOL_INIT_DEFAULT |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
163 value. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
164 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
165 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
166 .Fn mlk_alloc_pool_new |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
167 function requests a new slot from the |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
168 .Fa pool |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
169 and return it. If the current size has reached the capacity, it will be doubled |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
170 in that case it is possible that all previous pointer may be invalidated. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
171 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
172 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
173 .Fn mlk_alloc_pool_get |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
174 function returns the value at the given |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
175 .Fa index |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
176 from the |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
177 .Fa pool . |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
178 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
179 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
180 .Fn mlk_alloc_pool_shrink |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
181 function shrink the |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
182 .Fa pool |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
183 data to the exact number of elements in the array and return the memory region |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
184 which user takes full ownership. Once returned data is no longer needed, it must |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
185 be released with |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
186 .Fn mlk_alloc_free . |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
187 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
188 The pool is emptied and must be reinitialized using |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
189 .Fn mlk_alloc_pool_init |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
190 before reusing it. It is not necessary to call |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
191 .Fn mlk_alloc_pool_finish |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
192 but doing so is just no-op. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
193 .Pp |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
194 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
195 .Fn mlk_alloc_pool_finish |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
196 function finalizes the |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
197 .Fa pool |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
198 and all individual elements if a finalizer was set. You must call |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
199 .Fn mlk_alloc_pool_init |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
200 again before reusing it. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
201 .Sh EXAMPLES |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
202 .Ss Use a mlk_alloc_pool to increase an array while reading a file. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
203 .Bd -literal |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
204 /* A structure defined line by line inside a file in the form "x|y" */ |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
205 struct point { |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
206 int x; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
207 int y; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
208 }; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
209 |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
210 struct mlk_alloc_pool pool; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
211 struct point *point, *points; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
212 size_t pointsz; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
213 int x, y; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
214 |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
215 mlk_alloc_pool_init(&pool, sizeof (*point), NULL); |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
216 |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
217 /* Assume fp is a FILE pointer allocated by the user. */ |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
218 while (fscanf(fp, "%d|%d\\n", &x, &y) == 2) { |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
219 /* |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
220 * Returned pointer can be used to fill the region but must not be |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
221 * permanently referenced as it can get invalidated in the next |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
222 * iteration. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
223 */ |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
224 point = mlk_alloc_pool_new(&pool); |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
225 point->x = x; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
226 point->y = y; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
227 } |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
228 |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
229 /* |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
230 * Shrink the data into the appropriate array length. The pool can be safely |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
231 * discarded. |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
232 */ |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
233 pointsz = pool.size; |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
234 points = mlk_alloc_pool_shrink(&pool); |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
235 |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
236 for (size_t i = 0; i < pointsz; ++i) |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
237 point_draw(&points[i]); |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
238 .Ed |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
239 .Sh SEE ALSO |
442
9c3b3935f0aa
core: rework allocations
David Demelier <markand@malikania.fr>
parents:
438
diff
changeset
|
240 .Xr mlk-panic 3 , |
9c3b3935f0aa
core: rework allocations
David Demelier <markand@malikania.fr>
parents:
438
diff
changeset
|
241 .Xr mlk_alloc_array.3 , |
9c3b3935f0aa
core: rework allocations
David Demelier <markand@malikania.fr>
parents:
438
diff
changeset
|
242 .Xr mlk_alloc_new.3 , |
9c3b3935f0aa
core: rework allocations
David Demelier <markand@malikania.fr>
parents:
438
diff
changeset
|
243 .Xr mlk_alloc_set.3 |
438
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
244 .Sh AUTHORS |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
245 The |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
246 .Nm |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
247 library was written by |
25a56ca53ac2
core: update mlk-alloc module
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
248 .An David Demelier Aq Mt markand@malikania.fr . |