fsdev/p9array.h

   1 /*
   2  * P9Array - deep auto free C-array
   3  *
   4  * Copyright (c) 2021 Crudebyte
   5  *
   6  * Authors:
   7  *   Christian Schoenebeck <qemu_oss@crudebyte.com>
   8  *
   9  * Permission is hereby granted, free of charge, to any person obtaining a copy
  10  * of this software and associated documentation files (the "Software"), to deal
  11  * in the Software without restriction, including without limitation the rights
  12  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  13  * copies of the Software, and to permit persons to whom the Software is
  14  * furnished to do so, subject to the following conditions:
  15  *
  16  * The above copyright notice and this permission notice shall be included in
  17  * all copies or substantial portions of the Software.
  18  *
  19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  22  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  23  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  24  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  25  * THE SOFTWARE.
  26  */
  27 #ifndef QEMU_P9ARRAY_H
  28 #define QEMU_P9ARRAY_H
  29
  30 /**
  31  * P9Array provides a mechanism to access arrays in common C-style (e.g. by
  32  * square bracket [] operator) in conjunction with reference variables that
  33  * perform deep auto free of the array when leaving the scope of the auto
  34  * reference variable. That means not only is the array itself automatically
  35  * freed, but also memory dynamically allocated by the individual array
  36  * elements.
  37  *
  38  * Example:
  39  *
  40  * Consider the following user struct @c Foo which shall be used as scalar
  41  * (element) type of an array:
  42  * @code
  43  * typedef struct Foo {
  44  *     int i;
  45  *     char *s;
  46  * } Foo;
  47  * @endcode
  48  * and assume it has the following function to free memory allocated by @c Foo
  49  * instances:
  50  * @code
  51  * void free_foo(Foo *foo) {
  52  *     free(foo->s);
  53  * }
  54  * @endcode
  55  * Add the following to a shared header file:
  56  * @code
  57  * P9ARRAY_DECLARE_TYPE(Foo);
  58  * @endcode
  59  * and the following to a C unit file:
  60  * @code
  61  * P9ARRAY_DEFINE_TYPE(Foo, free_foo);
  62  * @endcode
  63  * Finally the array may then be used like this:
  64  * @code
  65  * void doSomething(size_t n) {
  66  *     P9ARRAY_REF(Foo) foos = NULL;
  67  *     P9ARRAY_NEW(Foo, foos, n);
  68  *     for (size_t i = 0; i < n; ++i) {
  69  *         foos[i].i = i;
  70  *         foos[i].s = calloc(4096, 1);
  71  *         snprintf(foos[i].s, 4096, "foo %d", i);
  72  *         if (...) {
  73  *             return; // array auto freed here
  74  *         }
  75  *     }
  76  *     // array auto freed here
  77  * }
  78  * @endcode
  79  */
  80
  81 /**
  82  * P9ARRAY_DECLARE_TYPE() - Declares an array type for the passed @scalar_type.
  83  *
  84  * @scalar_type: type of the individual array elements
  85  *
  86  * This is typically used from a shared header file.
  87  */
  88 #define P9ARRAY_DECLARE_TYPE(scalar_type) \
  89     typedef struct P9Array##scalar_type { \
  90         size_t len; \
  91         scalar_type first[]; \
  92     } P9Array##scalar_type; \
  93     \
  94     void p9array_new_##scalar_type(scalar_type **auto_var, size_t len); \
  95     void p9array_auto_free_##scalar_type(scalar_type **auto_var); \
  96
  97 /**
  98  * P9ARRAY_DEFINE_TYPE() - Defines an array type for the passed @scalar_type
  99  * and appropriate @scalar_cleanup_func.
 100  *
 101  * @scalar_type: type of the individual array elements
 102  * @scalar_cleanup_func: appropriate function to free memory dynamically
 103  *                       allocated by individual array elements before
 104  *
 105  * This is typically used from a C unit file.
 106  */
 107 #define P9ARRAY_DEFINE_TYPE(scalar_type, scalar_cleanup_func) \
 108     void p9array_new_##scalar_type(scalar_type **auto_var, size_t len) \
 109     { \
 110         p9array_auto_free_##scalar_type(auto_var); \
 111         P9Array##scalar_type *arr = g_malloc0(sizeof(P9Array##scalar_type) + \
 112             len * sizeof(scalar_type)); \
 113         arr->len = len; \
 114         *auto_var = &arr->first[0]; \
 115     } \
 116     \
 117     void p9array_auto_free_##scalar_type(scalar_type **auto_var) \
 118     { \
 119         scalar_type *first = (*auto_var); \
 120         if (!first) { \
 121             return; \
 122         } \
 123         P9Array##scalar_type *arr = (P9Array##scalar_type *) ( \
 124             ((char *)first) - offsetof(P9Array##scalar_type, first) \
 125         ); \
 126         for (size_t i = 0; i < arr->len; ++i) { \
 127             scalar_cleanup_func(&arr->first[i]); \
 128         } \
 129         g_free(arr); \
 130     } \
 131
 132 /**
 133  * P9ARRAY_REF() - Declare a reference variable for an array.
 134  *
 135  * @scalar_type: type of the individual array elements
 136  *
 137  * Used to declare a reference variable (unique pointer) for an array. After
 138  * leaving the scope of the reference variable, the associated array is
 139  * automatically freed.
 140  */
 141 #define P9ARRAY_REF(scalar_type) \
 142     __attribute((__cleanup__(p9array_auto_free_##scalar_type))) scalar_type*
 143
 144 /**
 145  * P9ARRAY_NEW() - Allocate a new array.
 146  *
 147  * @scalar_type: type of the individual array elements
 148  * @auto_var: destination reference variable
 149  * @len: amount of array elements to be allocated immediately
 150  *
 151  * Allocates a new array of passed @scalar_type with @len number of array
 152  * elements and assigns the created array to the reference variable
 153  * @auto_var.
 154  */
 155 #define P9ARRAY_NEW(scalar_type, auto_var, len) \
 156     QEMU_BUILD_BUG_MSG( \
 157         !__builtin_types_compatible_p(scalar_type, typeof(*auto_var)), \
 158         "P9Array scalar type mismatch" \
 159     ); \
 160     p9array_new_##scalar_type((&auto_var), len)
 161
 162 #endif /* QEMU_P9ARRAY_H */