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