2008-04-28 21:44:54 +00:00
|
|
|
/*
|
2012-12-12 18:06:53 +00:00
|
|
|
* viralloc.h: safer memory allocation
|
2008-04-28 21:44:54 +00:00
|
|
|
*
|
2014-06-30 07:33:41 +00:00
|
|
|
* Copyright (C) 2010-2014 Red Hat, Inc.
|
2008-04-28 21:44:54 +00:00
|
|
|
* Copyright (C) 2008 Daniel P. Berrange
|
|
|
|
|
*
|
|
|
|
|
* This library is free software; you can redistribute it and/or
|
|
|
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
|
|
|
* License as published by the Free Software Foundation; either
|
|
|
|
|
* version 2.1 of the License, or (at your option) any later version.
|
|
|
|
|
*
|
|
|
|
|
* This library is distributed in the hope that it will be useful,
|
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
|
|
* Lesser General Public License for more details.
|
|
|
|
|
*
|
|
|
|
|
* You should have received a copy of the GNU Lesser General Public
|
2012-09-20 22:30:55 +00:00
|
|
|
* License along with this library. If not, see
|
2012-07-21 10:06:23 +00:00
|
|
|
* <http://www.gnu.org/licenses/>.
|
2008-04-28 21:44:54 +00:00
|
|
|
*
|
|
|
|
|
*/
|
|
|
|
|
|
2019-06-18 16:12:45 +00:00
|
|
|
#pragma once
|
2008-04-28 21:44:54 +00:00
|
|
|
|
2019-06-18 16:12:45 +00:00
|
|
|
#include "internal.h"
|
2008-04-28 21:44:54 +00:00
|
|
|
|
2019-10-07 16:56:08 +00:00
|
|
|
/**
|
|
|
|
|
* DEPRECATION WARNING
|
|
|
|
|
*
|
|
|
|
|
* APIs in this file should only be used when modifying existing code.
|
|
|
|
|
* Consider converting existing code to use the new APIs when touching
|
|
|
|
|
* it. All new code must use the GLib memory allocation APIs and/or
|
|
|
|
|
* GLib array data types. See the hacking file for more guidance.
|
|
|
|
|
*/
|
|
|
|
|
|
2008-04-28 21:44:54 +00:00
|
|
|
/* Don't call these directly - use the macros below */
|
2019-08-29 14:23:31 +00:00
|
|
|
int virReallocN(void *ptrptr, size_t size, size_t count)
|
2019-10-14 12:25:14 +00:00
|
|
|
G_GNUC_WARN_UNUSED_RESULT ATTRIBUTE_NONNULL(1);
|
2019-08-29 14:23:31 +00:00
|
|
|
int virExpandN(void *ptrptr, size_t size, size_t *count, size_t add)
|
2019-10-14 12:25:14 +00:00
|
|
|
G_GNUC_WARN_UNUSED_RESULT ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(3);
|
2019-08-29 14:23:31 +00:00
|
|
|
int virResizeN(void *ptrptr, size_t size, size_t *alloc, size_t count, size_t desired)
|
2019-10-14 12:25:14 +00:00
|
|
|
G_GNUC_WARN_UNUSED_RESULT ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(3);
|
2011-02-03 15:09:00 +00:00
|
|
|
void virShrinkN(void *ptrptr, size_t size, size_t *count, size_t toremove)
|
2010-08-13 21:00:47 +00:00
|
|
|
ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(3);
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
int virInsertElementsN(void *ptrptr, size_t size, size_t at, size_t *countptr,
|
|
|
|
|
size_t add, void *newelem,
|
2019-08-29 14:23:31 +00:00
|
|
|
bool clearOriginal, bool inPlace)
|
2019-10-14 12:25:14 +00:00
|
|
|
G_GNUC_WARN_UNUSED_RESULT ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(4);
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
int virDeleteElementsN(void *ptrptr, size_t size, size_t at, size_t *countptr,
|
2013-03-07 13:38:37 +00:00
|
|
|
size_t toremove, bool inPlace)
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(4);
|
2019-08-29 14:23:31 +00:00
|
|
|
int virAllocVar(void *ptrptr, size_t struct_size, size_t element_size, size_t count)
|
2019-10-14 12:25:14 +00:00
|
|
|
G_GNUC_WARN_UNUSED_RESULT ATTRIBUTE_NONNULL(1);
|
2008-04-28 21:44:54 +00:00
|
|
|
|
2016-05-13 12:59:01 +00:00
|
|
|
void virDispose(void *ptrptr, size_t count, size_t element_size, size_t *countptr)
|
|
|
|
|
ATTRIBUTE_NONNULL(1);
|
2019-04-01 13:04:53 +00:00
|
|
|
void virDisposeString(char **strptr)
|
|
|
|
|
ATTRIBUTE_NONNULL(1);
|
2016-05-13 12:59:01 +00:00
|
|
|
|
2008-04-28 21:44:54 +00:00
|
|
|
/**
|
|
|
|
|
* VIR_REALLOC_N:
|
|
|
|
|
* @ptr: pointer to hold address of allocated memory
|
|
|
|
|
* @count: number of elements to allocate
|
|
|
|
|
*
|
|
|
|
|
* Re-allocate an array of 'count' elements, each sizeof(*ptr)
|
|
|
|
|
* bytes long and store the address of allocated memory in
|
2010-08-13 21:00:47 +00:00
|
|
|
* 'ptr'. If 'ptr' grew, the added memory is uninitialized.
|
2008-04-28 21:44:54 +00:00
|
|
|
*
|
alloc: make VIR_APPEND_ELEMENT safer
VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression
for 'size' had side effects. While no one in the current code base
was trying to pass side effects, we might as well be robust and
explicitly document our intentions.
* src/util/viralloc.c (virInsertElementsN): Add special case.
* src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it.
(VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N)
(VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT)
(VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document
which macros are safe in the presence of side effects.
* docs/hacking.html.in: Document this.
* HACKING: Regenerate.
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
|
|
|
* This macro is safe to use on arguments with side effects.
|
|
|
|
|
*
|
2019-08-29 14:23:31 +00:00
|
|
|
* Returns 0 on success, aborts on OOM
|
2013-06-07 08:37:25 +00:00
|
|
|
*/
|
2019-08-29 14:23:31 +00:00
|
|
|
#define VIR_REALLOC_N(ptr, count) virReallocN(&(ptr), sizeof(*(ptr)), (count))
|
2013-06-07 08:37:25 +00:00
|
|
|
|
2010-08-13 21:00:47 +00:00
|
|
|
/**
|
|
|
|
|
* VIR_EXPAND_N:
|
|
|
|
|
* @ptr: pointer to hold address of allocated memory
|
|
|
|
|
* @count: variable tracking number of elements currently allocated
|
|
|
|
|
* @add: number of elements to add
|
|
|
|
|
*
|
|
|
|
|
* Re-allocate an array of 'count' elements, each sizeof(*ptr)
|
|
|
|
|
* bytes long, to be 'count' + 'add' elements long, then store the
|
|
|
|
|
* address of allocated memory in 'ptr' and the new size in 'count'.
|
|
|
|
|
* The new elements are filled with zero.
|
|
|
|
|
*
|
alloc: make VIR_APPEND_ELEMENT safer
VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression
for 'size' had side effects. While no one in the current code base
was trying to pass side effects, we might as well be robust and
explicitly document our intentions.
* src/util/viralloc.c (virInsertElementsN): Add special case.
* src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it.
(VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N)
(VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT)
(VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document
which macros are safe in the presence of side effects.
* docs/hacking.html.in: Document this.
* HACKING: Regenerate.
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
|
|
|
* This macro is safe to use on arguments with side effects.
|
|
|
|
|
*
|
2019-08-29 14:23:31 +00:00
|
|
|
* Returns 0 on success, aborts on OOM
|
2010-08-13 21:00:47 +00:00
|
|
|
*/
|
2019-08-29 14:23:31 +00:00
|
|
|
#define VIR_EXPAND_N(ptr, count, add) virExpandN(&(ptr), sizeof(*(ptr)), &(count), add)
|
2013-06-07 08:37:25 +00:00
|
|
|
|
2010-08-14 15:42:51 +00:00
|
|
|
/**
|
|
|
|
|
* VIR_RESIZE_N:
|
|
|
|
|
* @ptr: pointer to hold address of allocated memory
|
|
|
|
|
* @alloc: variable tracking number of elements currently allocated
|
|
|
|
|
* @count: number of elements currently in use
|
|
|
|
|
* @add: minimum number of elements to additionally support
|
|
|
|
|
*
|
|
|
|
|
* Blindly using VIR_EXPAND_N(array, alloc, 1) in a loop scales
|
|
|
|
|
* quadratically, because every iteration must copy contents from
|
|
|
|
|
* all prior iterations. But amortized linear scaling can be achieved
|
|
|
|
|
* by tracking allocation size separately from the number of used
|
|
|
|
|
* elements, and growing geometrically only as needed.
|
|
|
|
|
*
|
|
|
|
|
* If 'count' + 'add' is larger than 'alloc', then geometrically reallocate
|
|
|
|
|
* the array of 'alloc' elements, each sizeof(*ptr) bytes long, and store
|
|
|
|
|
* the address of allocated memory in 'ptr' and the new size in 'alloc'.
|
|
|
|
|
* The new elements are filled with zero.
|
|
|
|
|
*
|
alloc: make VIR_APPEND_ELEMENT safer
VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression
for 'size' had side effects. While no one in the current code base
was trying to pass side effects, we might as well be robust and
explicitly document our intentions.
* src/util/viralloc.c (virInsertElementsN): Add special case.
* src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it.
(VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N)
(VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT)
(VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document
which macros are safe in the presence of side effects.
* docs/hacking.html.in: Document this.
* HACKING: Regenerate.
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
|
|
|
* This macro is safe to use on arguments with side effects.
|
|
|
|
|
*
|
2019-08-29 14:23:31 +00:00
|
|
|
* Returns 0 on success, aborts on OOM
|
2010-08-14 15:42:51 +00:00
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_RESIZE_N(ptr, alloc, count, add) \
|
2019-08-29 14:23:31 +00:00
|
|
|
virResizeN(&(ptr), sizeof(*(ptr)), &(alloc), count, add)
|
2013-06-07 08:37:25 +00:00
|
|
|
|
2010-08-13 21:00:47 +00:00
|
|
|
/**
|
|
|
|
|
* VIR_SHRINK_N:
|
|
|
|
|
* @ptr: pointer to hold address of allocated memory
|
|
|
|
|
* @count: variable tracking number of elements currently allocated
|
|
|
|
|
* @remove: number of elements to remove
|
|
|
|
|
*
|
|
|
|
|
* Re-allocate an array of 'count' elements, each sizeof(*ptr)
|
|
|
|
|
* bytes long, to be 'count' - 'remove' elements long, then store the
|
|
|
|
|
* address of allocated memory in 'ptr' and the new size in 'count'.
|
|
|
|
|
* If 'count' <= 'remove', the entire array is freed.
|
|
|
|
|
*
|
alloc: make VIR_APPEND_ELEMENT safer
VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression
for 'size' had side effects. While no one in the current code base
was trying to pass side effects, we might as well be robust and
explicitly document our intentions.
* src/util/viralloc.c (virInsertElementsN): Add special case.
* src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it.
(VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N)
(VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT)
(VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document
which macros are safe in the presence of side effects.
* docs/hacking.html.in: Document this.
* HACKING: Regenerate.
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
|
|
|
* This macro is safe to use on arguments with side effects.
|
|
|
|
|
*
|
2010-08-13 21:00:47 +00:00
|
|
|
* No return value.
|
|
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_SHRINK_N(ptr, count, remove) \
|
2010-08-13 21:00:47 +00:00
|
|
|
virShrinkN(&(ptr), sizeof(*(ptr)), &(count), remove)
|
|
|
|
|
|
2014-06-30 07:33:41 +00:00
|
|
|
/**
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
* VIR_TYPEMATCH:
|
|
|
|
|
*
|
|
|
|
|
* The following macro seems a bit cryptic, so it needs a thorough
|
|
|
|
|
* explanation. Its purpose is to check for assignment compatibility
|
|
|
|
|
* and identical size between two values without creating any side
|
|
|
|
|
* effects (by doing something silly like actually assigning one to
|
|
|
|
|
* the other). Note that it takes advantage of the C89-guaranteed
|
|
|
|
|
* property of sizeof() - it cannot have any side effects, so anything
|
|
|
|
|
* that happens inside sizeof() will not have any effect at runtime.
|
|
|
|
|
*
|
|
|
|
|
* VIR_TYPEMATCH evaluates to "1" if the two passed values are both
|
|
|
|
|
* assignment-compatible and the same size, and otherwise generates a
|
|
|
|
|
* compile-time error. It determines the result by performing the
|
|
|
|
|
* following three operations:
|
|
|
|
|
*
|
|
|
|
|
* * sizeof(*(a) = *(b)) assures that *a and *b are
|
|
|
|
|
* assignment-compatible (they may still have a different size
|
|
|
|
|
* though! e.g. longVar = intVar) (If not, there is a compile-time
|
|
|
|
|
* error. If so, the result of that subexpression is sizeof(*(a)),
|
|
|
|
|
* i.e. one element of the array)
|
|
|
|
|
*
|
|
|
|
|
* * sizeof(*(a) = *(b)) == sizeof(*(b)) checks if *a and *b are also
|
|
|
|
|
* of the same size (so that, e.g. you don't accidentally copy an
|
|
|
|
|
* int plus the random bytes following it into an array of long). It
|
|
|
|
|
* evaluates to 1 if they are the same, and 0 otherwise.
|
|
|
|
|
*
|
|
|
|
|
* * sizeof(char[2 * (result of previous step) - 1]) evaluates to 1
|
|
|
|
|
* if the previous step was successful (char [(2*1) - 1] i.e.
|
|
|
|
|
* char[1]), or generates a compile error if it wasn't successful
|
|
|
|
|
* (char[2*0 -1] i.e. char[-1], which isn't valid in C).
|
|
|
|
|
*
|
2013-02-23 15:30:38 +00:00
|
|
|
* So VIR_TYPEMATCH(a, b) will either abort the compile with an error,
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
* or evaluate to "1", and in the meantime check that we've actually
|
|
|
|
|
* added the correct &'s and/or *'s to the arguments. (Whew!)
|
|
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_TYPEMATCH(a, b) \
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
sizeof(char[2 * (sizeof(*(a) = *(b)) == sizeof(*(b))) - 1])
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* VIR_INSERT_ELEMENT:
|
|
|
|
|
* @ptr: pointer to array of objects (*not* ptr to ptr)
|
|
|
|
|
* @at: index within array where new elements should be added
|
|
|
|
|
* @count: variable tracking number of elements currently allocated
|
|
|
|
|
* @newelem: the new element to move into place (*not* a pointer to
|
|
|
|
|
* the element, but the element itself).
|
|
|
|
|
* (the original will be zeroed out if successful)
|
|
|
|
|
*
|
|
|
|
|
* Re-allocate an array of 'count' elements, each sizeof(*ptr) bytes
|
|
|
|
|
* long, to be 'count' + 1 elements long, then appropriately move
|
|
|
|
|
* the elements starting at ptr[at] up by 1 element, copy the
|
|
|
|
|
* item 'newelem' into ptr[at], then store the address of
|
|
|
|
|
* allocated memory in 'ptr' and the new size in 'count'.
|
|
|
|
|
*
|
|
|
|
|
* VIR_INSERT_ELEMENT_COPY is identical, but doesn't clear out the
|
|
|
|
|
* original element to 0 on success, so there are two copies of the
|
|
|
|
|
* element. This is useful if the "element" is actually just a
|
|
|
|
|
* pointer to the real data, and you want to maintain a reference to
|
|
|
|
|
* it for use after the insert is completed; but if the "element" is
|
|
|
|
|
* an object that points to other allocated memory, having multiple
|
|
|
|
|
* copies can cause problems (e.g. double free).
|
|
|
|
|
*
|
|
|
|
|
* VIR_INSERT_ELEMENT_*INPLACE are identical, but assume any necessary
|
|
|
|
|
* memory re-allocation has already been done.
|
|
|
|
|
*
|
|
|
|
|
* VIR_INSERT_ELEMENT_* all need to send "1" as the "add" argument to
|
|
|
|
|
* virInsertElementsN (which has the currently-unused capability of
|
|
|
|
|
* inserting multiple items at once). We use this to our advantage by
|
|
|
|
|
* replacing it with VIR_TYPECHECK(ptr, &newelem) so that we can be
|
|
|
|
|
* assured ptr and &newelem are of compatible types.
|
|
|
|
|
*
|
alloc: make VIR_APPEND_ELEMENT safer
VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression
for 'size' had side effects. While no one in the current code base
was trying to pass side effects, we might as well be robust and
explicitly document our intentions.
* src/util/viralloc.c (virInsertElementsN): Add special case.
* src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it.
(VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N)
(VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT)
(VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document
which macros are safe in the presence of side effects.
* docs/hacking.html.in: Document this.
* HACKING: Regenerate.
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
|
|
|
* These macros are safe to use on arguments with side effects.
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
*
|
2013-06-07 08:37:25 +00:00
|
|
|
* Returns -1 on failure (with OOM error reported), 0 on success
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_INSERT_ELEMENT(ptr, at, count, newelem) \
|
2017-11-03 12:09:47 +00:00
|
|
|
virInsertElementsN(&(ptr), sizeof(*(ptr)), at, &(count), \
|
2019-08-29 14:23:31 +00:00
|
|
|
VIR_TYPEMATCH(ptr, &(newelem)), &(newelem), true, false)
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_INSERT_ELEMENT_COPY(ptr, at, count, newelem) \
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
virInsertElementsN(&(ptr), sizeof(*(ptr)), at, &(count), \
|
2019-08-29 14:23:31 +00:00
|
|
|
VIR_TYPEMATCH(ptr, &(newelem)), &(newelem), false, false)
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_INSERT_ELEMENT_INPLACE(ptr, at, count, newelem) \
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
virInsertElementsN(&(ptr), sizeof(*(ptr)), at, &(count), \
|
2019-08-29 14:23:31 +00:00
|
|
|
VIR_TYPEMATCH(ptr, &(newelem)), &(newelem), true, true)
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_INSERT_ELEMENT_COPY_INPLACE(ptr, at, count, newelem) \
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
virInsertElementsN(&(ptr), sizeof(*(ptr)), at, &(count), \
|
2019-08-29 14:23:31 +00:00
|
|
|
VIR_TYPEMATCH(ptr, &(newelem)), &(newelem), false, true)
|
2013-06-07 08:37:25 +00:00
|
|
|
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
/**
|
|
|
|
|
* VIR_APPEND_ELEMENT:
|
|
|
|
|
* @ptr: pointer to array of objects (*not* ptr to ptr)
|
|
|
|
|
* @count: variable tracking number of elements currently allocated
|
|
|
|
|
* @newelem: the new element to move into place (*not* a pointer to
|
|
|
|
|
* the element, but the element itself).
|
|
|
|
|
* (the original will be zeroed out if successful)
|
|
|
|
|
*
|
|
|
|
|
* Re-allocate an array of 'count' elements, each sizeof(*ptr) bytes
|
|
|
|
|
* long, to be 'count' + 1 elements long, then copy the item from
|
|
|
|
|
* 'newelem' into ptr[count+1], and store the address of allocated
|
|
|
|
|
* memory in 'ptr' and the new size in 'count'. If 'newelem' is NULL,
|
|
|
|
|
* the new element at ptr[at] is instead filled with zero.
|
|
|
|
|
*
|
|
|
|
|
* VIR_APPEND_ELEMENT_COPY is identical, but doesn't clear out the
|
|
|
|
|
* original element to 0 on success, so there are two copies of the
|
|
|
|
|
* element. This is useful if the "element" is actually just a
|
|
|
|
|
* pointer to the real data, and you want to maintain a reference to
|
|
|
|
|
* it for use after the append is completed; but if the "element" is
|
|
|
|
|
* an object that points to other allocated memory, having multiple
|
|
|
|
|
* copies can cause problems (e.g. double free).
|
|
|
|
|
*
|
|
|
|
|
* VIR_APPEND_ELEMENT_*INPLACE are identical, but assume any
|
|
|
|
|
* necessary memory re-allocation has already been done.
|
|
|
|
|
*
|
|
|
|
|
* VIR_APPEND_ELEMENT_* all need to send "1" as the "add" argument to
|
|
|
|
|
* virInsertElementsN (which has the currently-unused capability of
|
|
|
|
|
* inserting multiple items at once). We use this to our advantage by
|
|
|
|
|
* replacing it with VIR_TYPECHECK(ptr, &newelem) so that we can be
|
|
|
|
|
* assured ptr and &newelem are of compatible types.
|
|
|
|
|
*
|
alloc: make VIR_APPEND_ELEMENT safer
VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression
for 'size' had side effects. While no one in the current code base
was trying to pass side effects, we might as well be robust and
explicitly document our intentions.
* src/util/viralloc.c (virInsertElementsN): Add special case.
* src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it.
(VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N)
(VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT)
(VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document
which macros are safe in the presence of side effects.
* docs/hacking.html.in: Document this.
* HACKING: Regenerate.
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
|
|
|
* These macros are safe to use on arguments with side effects.
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
*
|
2013-06-07 08:37:25 +00:00
|
|
|
* Returns -1 on failure (with OOM error reported), 0 on success
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_APPEND_ELEMENT(ptr, count, newelem) \
|
2017-11-03 12:09:47 +00:00
|
|
|
virInsertElementsN(&(ptr), sizeof(*(ptr)), -1, &(count), \
|
2019-08-29 14:23:31 +00:00
|
|
|
VIR_TYPEMATCH(ptr, &(newelem)), &(newelem), true, false)
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_APPEND_ELEMENT_COPY(ptr, count, newelem) \
|
2017-11-03 12:09:47 +00:00
|
|
|
virInsertElementsN(&(ptr), sizeof(*(ptr)), -1, &(count), \
|
2019-08-29 14:23:31 +00:00
|
|
|
VIR_TYPEMATCH(ptr, &(newelem)), &(newelem), false, false)
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_APPEND_ELEMENT_INPLACE(ptr, count, newelem) \
|
2017-11-03 12:09:47 +00:00
|
|
|
ignore_value(virInsertElementsN(&(ptr), sizeof(*(ptr)), -1, &(count), \
|
|
|
|
|
VIR_TYPEMATCH(ptr, &(newelem)), \
|
2019-08-29 14:23:31 +00:00
|
|
|
&(newelem), true, true))
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_APPEND_ELEMENT_COPY_INPLACE(ptr, count, newelem) \
|
2017-11-03 12:09:47 +00:00
|
|
|
ignore_value(virInsertElementsN(&(ptr), sizeof(*(ptr)), -1, &(count), \
|
|
|
|
|
VIR_TYPEMATCH(ptr, &(newelem)), \
|
2019-08-29 14:23:31 +00:00
|
|
|
&(newelem), false, true))
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
|
2013-06-07 08:37:25 +00:00
|
|
|
/* Quiet version of macros above */
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_APPEND_ELEMENT_QUIET(ptr, count, newelem) \
|
2019-08-29 14:23:31 +00:00
|
|
|
VIR_APPEND_ELEMENT(ptr, count, newelem)
|
2016-05-17 10:59:43 +00:00
|
|
|
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
/**
|
|
|
|
|
* VIR_DELETE_ELEMENT:
|
|
|
|
|
* @ptr: pointer to array of objects (*not* ptr to ptr)
|
|
|
|
|
* @at: index within array where new elements should be deleted
|
|
|
|
|
* @count: variable tracking number of elements currently allocated
|
|
|
|
|
*
|
|
|
|
|
* Re-allocate an array of 'count' elements, each sizeof(*ptr)
|
|
|
|
|
* bytes long, to be 'count' - 1 elements long, then store the
|
|
|
|
|
* address of allocated memory in 'ptr' and the new size in 'count'.
|
|
|
|
|
* If 'count' <= 1, the entire array is freed.
|
|
|
|
|
*
|
|
|
|
|
* VIR_DELETE_ELEMENT_INPLACE is identical, but assumes any
|
|
|
|
|
* necessary memory re-allocation will be done later.
|
|
|
|
|
*
|
alloc: make VIR_APPEND_ELEMENT safer
VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression
for 'size' had side effects. While no one in the current code base
was trying to pass side effects, we might as well be robust and
explicitly document our intentions.
* src/util/viralloc.c (virInsertElementsN): Add special case.
* src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it.
(VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N)
(VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT)
(VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document
which macros are safe in the presence of side effects.
* docs/hacking.html.in: Document this.
* HACKING: Regenerate.
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
|
|
|
* These macros are safe to use on arguments with side effects.
|
|
|
|
|
*
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
* Returns -1 on failure, 0 on success
|
|
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_DELETE_ELEMENT(ptr, at, count) \
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
virDeleteElementsN(&(ptr), sizeof(*(ptr)), at, &(count), 1, false)
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_DELETE_ELEMENT_INPLACE(ptr, at, count) \
|
util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.
The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)
VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
array of objects. The size of each object is determined
automatically by the macro using sizeof(*array). The new element's
contents are copied into the inserted space, then the original copy
of contents are 0'ed out (if everything else was
successful). Compile-time assignment and size compatibility between
the array and the new element is guaranteed (see explanation below
[*])
VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
that "inserts" one past the current last element.
VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
the original contents of newelem are not cleared to 0 (i.e. a copy
is made).
VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
array of objects. It's assumed that the element being deleted is
already saved elsewhere (or cleared, if that's what is appropriate).
All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).
Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.
[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).
But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-10-08 17:33:35 +00:00
|
|
|
virDeleteElementsN(&(ptr), sizeof(*(ptr)), at, &(count), 1, true)
|
|
|
|
|
|
2014-06-30 07:33:41 +00:00
|
|
|
/**
|
2010-04-05 17:11:34 +00:00
|
|
|
* VIR_ALLOC_VAR_OVERSIZED:
|
|
|
|
|
* @M: size of base structure
|
|
|
|
|
* @N: number of array elements in trailing array
|
|
|
|
|
* @S: size of trailing array elements
|
|
|
|
|
*
|
|
|
|
|
* Check to make sure that the requested allocation will not cause
|
2020-01-17 16:00:27 +00:00
|
|
|
* arithmetic overflow in the allocation size.
|
2010-04-05 17:11:34 +00:00
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_ALLOC_VAR_OVERSIZED(M, N, S) ((((size_t)-1) - (M)) / (S) < (N))
|
2010-04-05 17:11:34 +00:00
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* VIR_ALLOC_VAR:
|
|
|
|
|
* @ptr: pointer to hold address of allocated memory
|
|
|
|
|
* @type: element type of trailing array
|
|
|
|
|
* @count: number of array elements to allocate
|
|
|
|
|
*
|
|
|
|
|
* Allocate sizeof(*ptr) bytes plus an array of 'count' elements, each
|
|
|
|
|
* sizeof('type'). This sort of allocation is useful for receiving
|
|
|
|
|
* the data of certain ioctls and other APIs which return a struct in
|
|
|
|
|
* which the last element is an array of undefined length. The caller
|
|
|
|
|
* of this type of API is expected to know the length of the array
|
|
|
|
|
* that will be returned and allocate a suitable buffer to contain the
|
|
|
|
|
* returned data. C99 refers to these variable length objects as
|
|
|
|
|
* structs containing flexible array members.
|
alloc: make VIR_APPEND_ELEMENT safer
VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression
for 'size' had side effects. While no one in the current code base
was trying to pass side effects, we might as well be robust and
explicitly document our intentions.
* src/util/viralloc.c (virInsertElementsN): Add special case.
* src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it.
(VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N)
(VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT)
(VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document
which macros are safe in the presence of side effects.
* docs/hacking.html.in: Document this.
* HACKING: Regenerate.
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
|
|
|
*
|
|
|
|
|
* This macro is safe to use on arguments with side effects.
|
|
|
|
|
*
|
2019-08-29 14:23:31 +00:00
|
|
|
* Returns 0 on success, aborts on OOM
|
2010-04-05 17:11:34 +00:00
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_ALLOC_VAR(ptr, type, count) \
|
2019-08-29 14:23:31 +00:00
|
|
|
virAllocVar(&(ptr), sizeof(*(ptr)), sizeof(type), (count))
|
2013-06-07 08:37:25 +00:00
|
|
|
|
2008-04-28 21:44:54 +00:00
|
|
|
/**
|
|
|
|
|
* VIR_FREE:
|
|
|
|
|
* @ptr: pointer holding address to be freed
|
|
|
|
|
*
|
|
|
|
|
* Free the memory stored in 'ptr' and update to point
|
|
|
|
|
* to NULL.
|
alloc: make VIR_APPEND_ELEMENT safer
VIR_APPEND_ELEMENT(array, size, elem) was not safe if the expression
for 'size' had side effects. While no one in the current code base
was trying to pass side effects, we might as well be robust and
explicitly document our intentions.
* src/util/viralloc.c (virInsertElementsN): Add special case.
* src/util/viralloc.h (VIR_APPEND_ELEMENT): Use it.
(VIR_ALLOC, VIR_ALLOC_N, VIR_REALLOC_N, VIR_EXPAND_N)
(VIR_RESIZE_N, VIR_SHRINK_N, VIR_INSERT_ELEMENT)
(VIR_DELETE_ELEMENT, VIR_ALLOC_VAR, VIR_FREE): Document
which macros are safe in the presence of side effects.
* docs/hacking.html.in: Document this.
* HACKING: Regenerate.
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-06 22:21:15 +00:00
|
|
|
*
|
|
|
|
|
* This macro is safe to use on arguments with side effects.
|
2008-04-28 21:44:54 +00:00
|
|
|
*/
|
2020-03-05 08:42:23 +00:00
|
|
|
#define VIR_FREE(ptr) g_clear_pointer(&(ptr), g_free)
|
2013-01-22 14:15:37 +00:00
|
|
|
|
2016-05-13 12:59:01 +00:00
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* VIR_DISPOSE_N:
|
|
|
|
|
* @ptr: pointer holding address to be cleared and freed
|
|
|
|
|
* @count: count of elements in @ptr
|
|
|
|
|
*
|
2018-12-04 17:08:14 +00:00
|
|
|
* Clear the memory of the array of elements pointed to by 'ptr' of 'count'
|
2016-05-13 12:59:01 +00:00
|
|
|
* elements and free it. Update the pointer/count to NULL/0.
|
|
|
|
|
*
|
|
|
|
|
* This macro is safe to use on arguments with side effects.
|
|
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_DISPOSE_N(ptr, count) virDispose(1 ? (void *) &(ptr) : (ptr), 0, \
|
2016-05-13 12:59:01 +00:00
|
|
|
sizeof(*(ptr)), &(count))
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* VIR_DISPOSE_STRING:
|
|
|
|
|
* @ptr: pointer to a string to be cleared and freed
|
|
|
|
|
*
|
|
|
|
|
* Clears the string and frees the corresponding memory.
|
|
|
|
|
*
|
|
|
|
|
* This macro is not safe to be used on arguments with side effects.
|
|
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_DISPOSE_STRING(ptr) virDisposeString(&(ptr))
|
2016-05-13 12:59:01 +00:00
|
|
|
|
2019-04-01 13:04:53 +00:00
|
|
|
/**
|
|
|
|
|
* VIR_AUTODISPOSE_STR:
|
|
|
|
|
*
|
|
|
|
|
* Macro to automatically free and clear the memory allocated to
|
|
|
|
|
* the string variable declared with it by calling virDisposeString
|
|
|
|
|
* when the variable goes out of scope.
|
|
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_AUTODISPOSE_STR \
|
2019-04-01 13:04:53 +00:00
|
|
|
__attribute__((cleanup(virDisposeString))) char *
|
2016-05-13 12:59:01 +00:00
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* VIR_DISPOSE:
|
|
|
|
|
* @ptr: pointer to memory to be cleared and freed
|
|
|
|
|
*
|
|
|
|
|
* Clears and frees the corresponding memory.
|
|
|
|
|
*
|
|
|
|
|
* This macro is safe to be used on arguments with side effects.
|
|
|
|
|
*/
|
2019-06-18 16:12:45 +00:00
|
|
|
#define VIR_DISPOSE(ptr) virDispose(1 ? (void *) &(ptr) : (ptr), 1, \
|
|
|
|
|
sizeof(*(ptr)), NULL)
|
