]>
Commit | Line | Data |
---|---|---|
91b6eb11 | 1 | /* Type-safe arrays which grow dynamically. Shared definitions. |
dff8da6b | 2 | Copyright (C) 2017-2024 Free Software Foundation, Inc. |
91b6eb11 FW |
3 | This file is part of the GNU C Library. |
4 | ||
5 | The GNU C Library is free software; you can redistribute it and/or | |
6 | modify it under the terms of the GNU Lesser General Public | |
7 | License as published by the Free Software Foundation; either | |
8 | version 2.1 of the License, or (at your option) any later version. | |
9 | ||
10 | The GNU C Library is distributed in the hope that it will be useful, | |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
13 | Lesser General Public License for more details. | |
14 | ||
15 | You should have received a copy of the GNU Lesser General Public | |
16 | License along with the GNU C Library; if not, see | |
5a82c748 | 17 | <https://www.gnu.org/licenses/>. */ |
91b6eb11 FW |
18 | |
19 | /* To use the dynarray facility, you need to include | |
20 | <malloc/dynarray-skeleton.c> and define the parameter macros | |
21 | documented in that file. | |
22 | ||
23 | A minimal example which provides a growing list of integers can be | |
24 | defined like this: | |
25 | ||
26 | struct int_array | |
27 | { | |
28 | // Pointer to result array followed by its length, | |
29 | // as required by DYNARRAY_FINAL_TYPE. | |
30 | int *array; | |
31 | size_t length; | |
32 | }; | |
33 | ||
34 | #define DYNARRAY_STRUCT dynarray_int | |
35 | #define DYNARRAY_ELEMENT int | |
36 | #define DYNARRAY_PREFIX dynarray_int_ | |
37 | #define DYNARRAY_FINAL_TYPE struct int_array | |
38 | #include <malloc/dynarray-skeleton.c> | |
39 | ||
40 | To create a three-element array with elements 1, 2, 3, use this | |
41 | code: | |
42 | ||
43 | struct dynarray_int dyn; | |
44 | dynarray_int_init (&dyn); | |
45 | for (int i = 1; i <= 3; ++i) | |
46 | { | |
47 | int *place = dynarray_int_emplace (&dyn); | |
48 | assert (place != NULL); | |
49 | *place = i; | |
50 | } | |
51 | struct int_array result; | |
52 | bool ok = dynarray_int_finalize (&dyn, &result); | |
53 | assert (ok); | |
54 | assert (result.length == 3); | |
55 | assert (result.array[0] == 1); | |
56 | assert (result.array[1] == 2); | |
57 | assert (result.array[2] == 3); | |
58 | free (result.array); | |
59 | ||
60 | If the elements contain resources which must be freed, define | |
61 | DYNARRAY_ELEMENT_FREE appropriately, like this: | |
62 | ||
63 | struct str_array | |
64 | { | |
65 | char **array; | |
66 | size_t length; | |
67 | }; | |
68 | ||
69 | #define DYNARRAY_STRUCT dynarray_str | |
70 | #define DYNARRAY_ELEMENT char * | |
71 | #define DYNARRAY_ELEMENT_FREE(ptr) free (*ptr) | |
72 | #define DYNARRAY_PREFIX dynarray_str_ | |
73 | #define DYNARRAY_FINAL_TYPE struct str_array | |
74 | #include <malloc/dynarray-skeleton.c> | |
75 | ||
76 | Compared to scratch buffers, dynamic arrays have the following | |
77 | features: | |
78 | ||
79 | - They have an element type, and are not just an untyped buffer of | |
80 | bytes. | |
81 | ||
82 | - When growing, previously stored elements are preserved. (It is | |
83 | expected that scratch_buffer_grow_preserve and | |
84 | scratch_buffer_set_array_size eventually go away because all | |
85 | current users are moved to dynamic arrays.) | |
86 | ||
87 | - Scratch buffers have a more aggressive growth policy because | |
88 | growing them typically means a retry of an operation (across an | |
89 | NSS service module boundary), which is expensive. | |
90 | ||
91 | - For the same reason, scratch buffers have a much larger initial | |
92 | stack allocation. */ | |
93 | ||
94 | #ifndef _DYNARRAY_H | |
95 | #define _DYNARRAY_H | |
96 | ||
97 | #include <stdbool.h> | |
98 | #include <stddef.h> | |
99 | #include <string.h> | |
100 | ||
101 | struct dynarray_header | |
102 | { | |
103 | size_t used; | |
104 | size_t allocated; | |
105 | void *array; | |
106 | }; | |
107 | ||
108 | /* Marker used in the allocated member to indicate that an error was | |
109 | encountered. */ | |
110 | static inline size_t | |
111 | __dynarray_error_marker (void) | |
112 | { | |
113 | return -1; | |
114 | } | |
115 | ||
116 | /* Internal function. See the has_failed function in | |
117 | dynarray-skeleton.c. */ | |
118 | static inline bool | |
119 | __dynarray_error (struct dynarray_header *list) | |
120 | { | |
121 | return list->allocated == __dynarray_error_marker (); | |
122 | } | |
123 | ||
124 | /* Internal function. Enlarge the dynamically allocated area of the | |
125 | array to make room for one more element. SCRATCH is a pointer to | |
126 | the scratch area (which is not heap-allocated and must not be | |
127 | freed). ELEMENT_SIZE is the size, in bytes, of one element. | |
128 | Return false on failure, true on success. */ | |
129 | bool __libc_dynarray_emplace_enlarge (struct dynarray_header *, | |
130 | void *scratch, size_t element_size); | |
91b6eb11 FW |
131 | |
132 | /* Internal function. Enlarge the dynamically allocated area of the | |
133 | array to make room for at least SIZE elements (which must be larger | |
134 | than the existing used part of the dynamic array). SCRATCH is a | |
135 | pointer to the scratch area (which is not heap-allocated and must | |
136 | not be freed). ELEMENT_SIZE is the size, in bytes, of one element. | |
137 | Return false on failure, true on success. */ | |
138 | bool __libc_dynarray_resize (struct dynarray_header *, size_t size, | |
139 | void *scratch, size_t element_size); | |
91b6eb11 FW |
140 | |
141 | /* Internal function. Like __libc_dynarray_resize, but clear the new | |
142 | part of the dynamic array. */ | |
143 | bool __libc_dynarray_resize_clear (struct dynarray_header *, size_t size, | |
144 | void *scratch, size_t element_size); | |
91b6eb11 FW |
145 | |
146 | /* Internal type. */ | |
147 | struct dynarray_finalize_result | |
148 | { | |
149 | void *array; | |
150 | size_t length; | |
151 | }; | |
152 | ||
153 | /* Internal function. Copy the dynamically-allocated area to an | |
154 | explicitly-sized heap allocation. SCRATCH is a pointer to the | |
155 | embedded scratch space. ELEMENT_SIZE is the size, in bytes, of the | |
156 | element type. On success, true is returned, and pointer and length | |
157 | are written to *RESULT. On failure, false is returned. The caller | |
158 | has to take care of some of the memory management; this function is | |
159 | expected to be called from dynarray-skeleton.c. */ | |
160 | bool __libc_dynarray_finalize (struct dynarray_header *list, void *scratch, | |
161 | size_t element_size, | |
162 | struct dynarray_finalize_result *result); | |
91b6eb11 FW |
163 | |
164 | ||
165 | /* Internal function. Terminate the process after an index error. | |
166 | SIZE is the number of elements of the dynamic array. INDEX is the | |
167 | lookup index which triggered the failure. */ | |
de0e1b45 | 168 | _Noreturn void __libc_dynarray_at_failure (size_t size, size_t index); |
5b83faf6 FW |
169 | |
170 | #ifndef _ISOMAC | |
171 | libc_hidden_proto (__libc_dynarray_emplace_enlarge) | |
172 | libc_hidden_proto (__libc_dynarray_resize) | |
173 | libc_hidden_proto (__libc_dynarray_resize_clear) | |
174 | libc_hidden_proto (__libc_dynarray_finalize) | |
91b6eb11 | 175 | libc_hidden_proto (__libc_dynarray_at_failure) |
5b83faf6 | 176 | #endif |
91b6eb11 FW |
177 | |
178 | #endif /* _DYNARRAY_H */ |