71cf9af189c97a8ef6d30ffabce1f9ba0946928b
[lttng-tools.git] / src / common / dynamic-array.h
1 /*
2 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
3 *
4 * SPDX-License-Identifier: LGPL-2.1-only
5 *
6 */
7
8 #ifndef LTTNG_DYNAMIC_ARRAY_H
9 #define LTTNG_DYNAMIC_ARRAY_H
10
11 #include <common/dynamic-buffer.h>
12 #include <assert.h>
13
14 typedef void (*lttng_dynamic_array_element_destructor)(void *element);
15 typedef void (*lttng_dynamic_pointer_array_destructor)(void *ptr);
16
17 struct lttng_dynamic_array {
18 struct lttng_dynamic_buffer buffer;
19 size_t element_size;
20 size_t size;
21 lttng_dynamic_array_element_destructor destructor;
22 };
23
24 struct lttng_dynamic_pointer_array {
25 struct lttng_dynamic_array array;
26 };
27
28 /*
29 * Initialize a resizable array of fixed-size elements. This performs no
30 * allocation and can't fail.
31 */
32 LTTNG_HIDDEN
33 void lttng_dynamic_array_init(struct lttng_dynamic_array *array,
34 size_t element_size,
35 lttng_dynamic_array_element_destructor destructor);
36
37 /*
38 * Returns the number of elements in the dynamic array.
39 */
40 static inline
41 size_t lttng_dynamic_array_get_count(
42 const struct lttng_dynamic_array *array)
43 {
44 return array->size;
45 }
46
47 /*
48 * Returns a pointer to the element. Mutating operations on the array invalidate
49 * the returned pointer.
50 */
51 static inline
52 void *lttng_dynamic_array_get_element(const struct lttng_dynamic_array *array,
53 size_t element_index)
54 {
55 assert(element_index < array->size);
56 return array->buffer.data + (element_index * array->element_size);
57 }
58
59 /*
60 * Set the array's element count to new_element_count. Any added element will
61 * be zeroed.
62 *
63 * Be careful to expand the array's element count _before_ calling out external
64 * APIs (e.g. read(3)) which may populate the buffer as setting the element
65 * count after will zero-out the result of the operation.
66 *
67 * Shrinking an array does not zero the old content. If the buffer may contain
68 * sensititve information, it must be cleared manually _before_ changing the
69 * size.
70 *
71 * NOTE: It is striclty _invalid_ to access memory after _size_, regardless
72 * of prior calls to set_capacity().
73 */
74 LTTNG_HIDDEN
75 int lttng_dynamic_array_set_count(struct lttng_dynamic_array *array,
76 size_t new_element_count);
77
78 /*
79 * Add an element to the end of a dynamic array. The array's element count is
80 * increased by one and its underlying capacity is adjusted automatically.
81 *
82 * element is a pointer to the element to add (copy) to the array.
83 */
84 LTTNG_HIDDEN
85 int lttng_dynamic_array_add_element(struct lttng_dynamic_array *array,
86 const void *element);
87
88 /*
89 * Remove an element from the dynamic array. The array's element count is
90 * decreased by one and the following elements are shifted to take its place
91 * (when applicable).
92 */
93 LTTNG_HIDDEN
94 int lttng_dynamic_array_remove_element(struct lttng_dynamic_array *array,
95 size_t element_index);
96
97 /* Release any memory used by the dynamic array. */
98 LTTNG_HIDDEN
99 void lttng_dynamic_array_reset(struct lttng_dynamic_array *array);
100
101 /* Remove all elements from the dynamic array. */
102 LTTNG_HIDDEN
103 void lttng_dynamic_array_clear(struct lttng_dynamic_array *array);
104
105 /*
106 * Specialization of lttng_dynamic_array for pointers. This utility
107 * is built under the assumption that pointer sizes are equal
108 * for all data types on supported architectures. Revisit this in the event
109 * of a port to an Harvard architecture.
110 */
111
112 /*
113 * Initialize a resizable array of fixed-size elements. This performs no
114 * allocation and can't fail.
115 */
116 LTTNG_HIDDEN
117 void lttng_dynamic_pointer_array_init(
118 struct lttng_dynamic_pointer_array *array,
119 lttng_dynamic_pointer_array_destructor destructor);
120
121 /*
122 * Returns the number of pointers in the dynamic pointer array.
123 */
124 static inline
125 size_t lttng_dynamic_pointer_array_get_count(
126 const struct lttng_dynamic_pointer_array *array)
127 {
128 return lttng_dynamic_array_get_count(&array->array);
129 }
130
131 /*
132 * Returns the pointer at index `index`.
133 */
134 static inline
135 void *lttng_dynamic_pointer_array_get_pointer(
136 const struct lttng_dynamic_pointer_array *array, size_t index)
137 {
138 void **element = lttng_dynamic_array_get_element(&array->array, index);
139
140 return *element;
141 }
142
143 /*
144 * Returns the pointer at index `index`, sets the array slot to NULL. Does not
145 * run the destructor.
146 */
147
148 static inline
149 void *lttng_dynamic_pointer_array_steal_pointer(
150 struct lttng_dynamic_pointer_array *array, size_t index)
151 {
152 void **p_element = lttng_dynamic_array_get_element(&array->array, index);
153 void *element = *p_element;
154
155 *p_element = NULL;
156
157 return element;
158 }
159
160 /*
161 * Add a pointer to the end of a dynamic pointer array. The array's element
162 * count is increased by one and its underlying capacity is adjusted
163 * automatically.
164 */
165 static inline
166 int lttng_dynamic_pointer_array_add_pointer(
167 struct lttng_dynamic_pointer_array *array, void *pointer)
168 {
169 return lttng_dynamic_array_add_element(&array->array, &pointer);
170 }
171
172 /*
173 * Remove a pointer from a dynamic pointer array. The array's element
174 * count is decreased by one and the following pointers are shifted to
175 * take the place of the removed pointer (if applicable).
176 */
177 LTTNG_HIDDEN
178 int lttng_dynamic_pointer_array_remove_pointer(
179 struct lttng_dynamic_pointer_array *array, size_t index);
180
181 /* Release any memory used by the dynamic array. */
182 LTTNG_HIDDEN
183 void lttng_dynamic_pointer_array_reset(
184 struct lttng_dynamic_pointer_array *array);
185
186 /* Remove all elements from the dynamic pointer array. */
187 LTTNG_HIDDEN
188 void lttng_dynamic_pointer_array_clear(
189 struct lttng_dynamic_pointer_array *array);
190
191 #endif /* LTTNG_DYNAMIC_ARRAY_H */
This page took 0.050498 seconds and 5 git commands to generate.