Mercurial > molko

annotate man/mlk-alloc.3 @ 546:b7da58230a66

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cmake: fix for RHEL
author David Demelier <markand@malikania.fr>
date Mon, 06 Mar 2023 20:01:00 +0100
parents 9c3b3935f0aa
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 .