dynamic-array: fix documentation of lttng_dynamic_pointer_array_get_pointer
[lttng-tools.git] / src / common / dynamic-array.h
1 /*
2 * Copyright (C) 2019 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
3 *
4 * This program is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License, version 2.1 only,
6 * as published by the Free Software Foundation.
7 *
8 * This program is distributed in the hope that it will be useful, but WITHOUT
9 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
11 * for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this program; if not, write to the Free Software Foundation,
15 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16 */
17
18 #ifndef LTTNG_DYNAMIC_ARRAY_H
19 #define LTTNG_DYNAMIC_ARRAY_H
20
21 #include <common/dynamic-buffer.h>
22 #include <assert.h>
23
24 typedef void (*lttng_dynamic_array_element_destructor)(void *element);
25 typedef void (*lttng_dynamic_pointer_array_destructor)(void *ptr);
26
27 struct lttng_dynamic_array {
28 struct lttng_dynamic_buffer buffer;
29 size_t element_size;
30 size_t size;
31 lttng_dynamic_array_element_destructor destructor;
32 };
33
34 struct lttng_dynamic_pointer_array {
35 struct lttng_dynamic_array array;
36 };
37
38 /*
39 * Initialize a resizable array of fixed-size elements. This performs no
40 * allocation and can't fail.
41 */
42 LTTNG_HIDDEN
43 void lttng_dynamic_array_init(struct lttng_dynamic_array *array,
44 size_t element_size,
45 lttng_dynamic_array_element_destructor destructor);
46
47 /*
48 * Returns the number of elements in the dynamic array.
49 */
50 static inline
51 size_t lttng_dynamic_array_get_count(
52 const struct lttng_dynamic_array *array)
53 {
54 return array->size;
55 }
56
57 /*
58 * Returns a pointer to the element. Mutating operations on the array invalidate
59 * the returned pointer.
60 */
61 static inline
62 void *lttng_dynamic_array_get_element(const struct lttng_dynamic_array *array,
63 size_t element_index)
64 {
65 assert(element_index < array->size);
66 return array->buffer.data + (element_index * array->element_size);
67 }
68
69 /*
70 * Add an element to the end of a dynamic array. The array's element count is
71 * increased by one and its underlying capacity is adjusted automatically.
72 *
73 * element is a pointer to the element to add (copy) to the array.
74 */
75 LTTNG_HIDDEN
76 int lttng_dynamic_array_add_element(struct lttng_dynamic_array *array,
77 const void *element);
78
79 /*
80 * Remove an element from the dynamic array. The array's element count is
81 * decreased by one and the following elements are shifted to take its place
82 * (when applicable).
83 */
84 LTTNG_HIDDEN
85 int lttng_dynamic_array_remove_element(struct lttng_dynamic_array *array,
86 size_t element_index);
87
88 /* Release any memory used by the dynamic array. */
89 LTTNG_HIDDEN
90 void lttng_dynamic_array_reset(struct lttng_dynamic_array *array);
91
92
93 /*
94 * Specialization of lttng_dynamic_array for pointers. This utility
95 * is built under the assumption that pointer sizes are equal
96 * for all data types on supported architectures. Revisit this in the event
97 * of a port to an Harvard architecture.
98 */
99
100 /*
101 * Initialize a resizable array of fixed-size elements. This performs no
102 * allocation and can't fail.
103 */
104 LTTNG_HIDDEN
105 void lttng_dynamic_pointer_array_init(
106 struct lttng_dynamic_pointer_array *array,
107 lttng_dynamic_pointer_array_destructor destructor);
108
109 /*
110 * Returns the number of pointers in the dynamic pointer array.
111 */
112 static inline
113 size_t lttng_dynamic_pointer_array_get_count(
114 const struct lttng_dynamic_pointer_array *array)
115 {
116 return lttng_dynamic_array_get_count(&array->array);
117 }
118
119 /*
120 * Returns the pointer at index `index`.
121 */
122 static inline
123 void *lttng_dynamic_pointer_array_get_pointer(
124 const struct lttng_dynamic_pointer_array *array, size_t index)
125 {
126 void **element = lttng_dynamic_array_get_element(&array->array, index);
127
128 return *element;
129 }
130
131 /*
132 * Add a pointer to the end of a dynamic pointer array. The array's element
133 * count is increased by one and its underlying capacity is adjusted
134 * automatically.
135 */
136 static inline
137 int lttng_dynamic_pointer_array_add_pointer(
138 struct lttng_dynamic_pointer_array *array, void *pointer)
139 {
140 return lttng_dynamic_array_add_element(&array->array, &pointer);
141 }
142
143 /*
144 * Remove a pointer from a dynamic pointer array. The array's element
145 * count is decreased by one and the following pointers are shifted to
146 * take the place of the removed pointer (if applicable).
147 */
148 LTTNG_HIDDEN
149 int lttng_dynamic_pointer_array_remove_pointer(
150 struct lttng_dynamic_pointer_array *array, size_t index);
151
152 /* Release any memory used by the dynamic array. */
153 LTTNG_HIDDEN
154 void lttng_dynamic_pointer_array_reset(
155 struct lttng_dynamic_pointer_array *array);
156
157 #endif /* LTTNG_DYNAMIC_ARRAY_H */
This page took 0.044749 seconds and 4 git commands to generate.