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 */