xref: /openbmc/qemu/fsdev/p9array.h (revision bfe7bf85)
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