dynamic-array: fix documentation of lttng_dynamic_pointer_array_get_pointer
[lttng-tools.git] / src / common / dynamic-array.h
CommitLineData
2c5ff4e4
JG
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
93bed9fe
JG
24typedef void (*lttng_dynamic_array_element_destructor)(void *element);
25typedef void (*lttng_dynamic_pointer_array_destructor)(void *ptr);
26
2c5ff4e4
JG
27struct lttng_dynamic_array {
28 struct lttng_dynamic_buffer buffer;
29 size_t element_size;
30 size_t size;
93bed9fe 31 lttng_dynamic_array_element_destructor destructor;
2c5ff4e4
JG
32};
33
34struct lttng_dynamic_pointer_array {
35 struct lttng_dynamic_array array;
36};
37
2c5ff4e4
JG
38/*
39 * Initialize a resizable array of fixed-size elements. This performs no
40 * allocation and can't fail.
41 */
42LTTNG_HIDDEN
43void lttng_dynamic_array_init(struct lttng_dynamic_array *array,
93bed9fe
JG
44 size_t element_size,
45 lttng_dynamic_array_element_destructor destructor);
2c5ff4e4
JG
46
47/*
48 * Returns the number of elements in the dynamic array.
49 */
50static inline
51size_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 */
61static inline
62void *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 */
75LTTNG_HIDDEN
76int lttng_dynamic_array_add_element(struct lttng_dynamic_array *array,
77 const void *element);
78
93bed9fe
JG
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 */
84LTTNG_HIDDEN
85int lttng_dynamic_array_remove_element(struct lttng_dynamic_array *array,
86 size_t element_index);
87
2c5ff4e4
JG
88/* Release any memory used by the dynamic array. */
89LTTNG_HIDDEN
93bed9fe 90void lttng_dynamic_array_reset(struct lttng_dynamic_array *array);
2c5ff4e4
JG
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 */
104LTTNG_HIDDEN
105void lttng_dynamic_pointer_array_init(
93bed9fe
JG
106 struct lttng_dynamic_pointer_array *array,
107 lttng_dynamic_pointer_array_destructor destructor);
2c5ff4e4
JG
108
109/*
110 * Returns the number of pointers in the dynamic pointer array.
111 */
112static inline
113size_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/*
14c4262b 120 * Returns the pointer at index `index`.
2c5ff4e4
JG
121 */
122static inline
123void *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 */
136static inline
137int 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
93bed9fe
JG
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 */
0186592a 148LTTNG_HIDDEN
93bed9fe 149int lttng_dynamic_pointer_array_remove_pointer(
0186592a 150 struct lttng_dynamic_pointer_array *array, size_t index);
93bed9fe 151
2c5ff4e4
JG
152/* Release any memory used by the dynamic array. */
153LTTNG_HIDDEN
154void lttng_dynamic_pointer_array_reset(
93bed9fe 155 struct lttng_dynamic_pointer_array *array);
2c5ff4e4
JG
156
157#endif /* LTTNG_DYNAMIC_ARRAY_H */
This page took 0.061173 seconds and 4 git commands to generate.