/*
* P9Array - deep auto free C-array
*
* Copyright (c) 2021 Crudebyte
*
* Authors:
* Christian Schoenebeck <qemu_oss@crudebyte.com>
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef QEMU_P9ARRAY_H
#define QEMU_P9ARRAY_H
#include "qemu/compiler.h"
/**
* P9Array provides a mechanism to access arrays in common C-style (e.g. by
* square bracket [] operator) in conjunction with reference variables that
* perform deep auto free of the array when leaving the scope of the auto
* reference variable. That means not only is the array itself automatically
* freed, but also memory dynamically allocated by the individual array
* elements.
*
* Example:
*
* Consider the following user struct @c Foo which shall be used as scalar
* (element) type of an array:
* @code
* typedef struct Foo {
* int i;
* char *s;
* } Foo;
* @endcode
* and assume it has the following function to free memory allocated by @c Foo
* instances:
* @code
* void free_foo(Foo *foo) {
* free(foo->s);
* }
* @endcode
* Add the following to a shared header file:
* @code
* P9ARRAY_DECLARE_TYPE(Foo);
* @endcode
* and the following to a C unit file:
* @code
* P9ARRAY_DEFINE_TYPE(Foo, free_foo);
* @endcode
* Finally the array may then be used like this:
* @code
* void doSomething(size_t n) {
* P9ARRAY_REF(Foo) foos = NULL;
* P9ARRAY_NEW(Foo, foos, n);
* for (size_t i = 0; i < n; ++i) {
* foos[i].i = i;
* foos[i].s = calloc(4096, 1);
* snprintf(foos[i].s, 4096, "foo %d", i);
* if (...) {
* return; // array auto freed here
* }
* }
* // array auto freed here
* }
* @endcode
*/
/**
* P9ARRAY_DECLARE_TYPE() - Declares an array type for the passed @scalar_type.
*
* @scalar_type: type of the individual array elements
*
* This is typically used from a shared header file.
*/
#define P9ARRAY_DECLARE_TYPE(scalar_type) \
typedef struct P9Array##scalar_type { \
size_t len; \
scalar_type first[]; \
} P9Array##scalar_type; \
\
void p9array_new_##scalar_type(scalar_type **auto_var, size_t len); \
void p9array_auto_free_##scalar_type(scalar_type **auto_var); \
/**
* P9ARRAY_DEFINE_TYPE() - Defines an array type for the passed @scalar_type
* and appropriate @scalar_cleanup_func.
*
* @scalar_type: type of the individual array elements
* @scalar_cleanup_func: appropriate function to free memory dynamically
* allocated by individual array elements before
*
* This is typically used from a C unit file.
*/
#define P9ARRAY_DEFINE_TYPE(scalar_type, scalar_cleanup_func) \
void p9array_new_##scalar_type(scalar_type **auto_var, size_t len) \
{ \
p9array_auto_free_##scalar_type(auto_var); \
P9Array##scalar_type *arr = g_malloc0(sizeof(P9Array##scalar_type) + \
len * sizeof(scalar_type)); \
arr->len = len; \
*auto_var = &arr->first[0]; \
} \
\
void p9array_auto_free_##scalar_type(scalar_type **auto_var) \
{ \
scalar_type *first = (*auto_var); \
if (!first) { \
return; \
} \
P9Array##scalar_type *arr = (P9Array##scalar_type *) ( \
((char *)first) - offsetof(P9Array##scalar_type, first) \
); \
for (size_t i = 0; i < arr->len; ++i) { \
scalar_cleanup_func(&arr->first[i]); \
} \
g_free(arr); \
} \
/**
* P9ARRAY_REF() - Declare a reference variable for an array.
*
* @scalar_type: type of the individual array elements
*
* Used to declare a reference variable (unique pointer) for an array. After
* leaving the scope of the reference variable, the associated array is
* automatically freed.
*/
#define P9ARRAY_REF(scalar_type) \
__attribute((__cleanup__(p9array_auto_free_##scalar_type))) scalar_type*
/**
* P9ARRAY_NEW() - Allocate a new array.
*
* @scalar_type: type of the individual array elements
* @auto_var: destination reference variable
* @len: amount of array elements to be allocated immediately
*
* Allocates a new array of passed @scalar_type with @len number of array
* elements and assigns the created array to the reference variable
* @auto_var.
*/
#define P9ARRAY_NEW(scalar_type, auto_var, len) \
QEMU_BUILD_BUG_MSG( \
!__builtin_types_compatible_p(scalar_type, typeof(*auto_var)), \
"P9Array scalar type mismatch" \
); \
p9array_new_##scalar_type((&auto_var), len)
#endif /* QEMU_P9ARRAY_H */
