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