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>
Make sure at compile time that the scalar type of the array
requested to be created via P9ARRAY_NEW() matches the scalar
type of the passed auto reference variable (unique pointer).
Suggested-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Christian Schoenebeck <qemu_oss@crudebyte.com>
Message-Id: <c1965e2a096835dc9e1d4d659dfb15d96755cbe0.1633097129.git.qemu_oss@crudebyte.com>
Implements deep auto free of arrays while retaining common C-style
squared bracket access. Main purpose of this API is to get rid of
error prone individual array deallocation pathes in user code, i.e.
turning something like this:
void doSomething(size_t n) {
Foo *foos = malloc(n * sizeof(Foo));
for (...) {
foos[i].s = malloc(...);
if (...) {
goto out;
}
}
out:
if (...) {
for (...) {
/* deep deallocation */
free(foos[i].s);
}
/* array deallocation */
free(foos);
}
}
into something more simple and safer like:
void doSomething(size_t n) {
P9ARRAY_REF(Foo) foos = NULL;
P9ARRAY_NEW(Foo, foos, n);
for (...) {
foos[i].s = malloc(...);
if (...) {
return; /* array auto freed here */
}
}
/* array auto freed here */
}
Unlike GArray, P9Array does not require special macros, function
calls or struct member dereferencing to access the individual array
elements:
C-array = P9Array: vs. GArray:
for (...) { | for (...) {
... = arr[i].m; | ... = g_array_index(arr, Foo, i).m;
arr[i].m = ... ; | g_array_index(arr, Foo, i).m = ... ;
} | }
So existing C-style array code can be retained with only very little
changes; basically limited to replacing array allocation call and of
course removing individual array deallocation pathes.
In this initial version P9Array only supports the concept of unique
pointers, i.e. it does not support reference counting. The array (and
all dynamically allocated memory of individual array elements) is auto
freed once execution leaves the scope of the reference variable (unique
pointer) associated with the array.
Internally a flex array struct is used in combination with macros
spanned over a continuous memory space for both the array's meta data
(private) and the actual C-array user data (public):
struct P9Array##scalar_type {
size_t len; /* private, hidden from user code */
scalar_type first[]; /* public, directly exposed to user code */
};
Which has the advantage that the compiler automatically takes care
about correct padding, alignment and overall size for all scalar data
types on all systems and that the user space exposed pointer can
directly be translated back and forth between user space C-array
pointer and internal P9Array struct whenever needed, in a type-safe
manner.
This header file is released under MIT license, to allow this file
being used in other C-projects as well. The common QEMU license
GPL2+ might have construed a conflict for other projects.
Signed-off-by: Christian Schoenebeck <qemu_oss@crudebyte.com>
Message-Id: <a954ef47b5ac26085a16c5c2aec8695374e0424d.1633097129.git.qemu_oss@crudebyte.com>
