mirror of
https://gitlab.com/qemu-project/qemu
synced 2024-09-06 18:05:37 +00:00
![Christian Schoenebeck](/assets/img/avatar_default.png)
API doc comments in QEMU are supposed to be in kerneldoc format, so convert API doc comments from Doxygen format to kerneldoc format. Signed-off-by: Christian Schoenebeck <qemu_oss@crudebyte.com> Reviewed-by: Greg Kurz <groug@kaod.org> Message-Id: <2e2d46a402560f155de322d95789ba107d728885.1646314856.git.qemu_oss@crudebyte.com>
165 lines
5.4 KiB
C
165 lines
5.4 KiB
C
/*
|
|
* 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 */
|