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