src/common/dynamic-array.hpp

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