Geogram
Version 1.9.1
A programming library of geometric algorithms
|
Efficient storage for array of arrays. More...
#include <geogram/basic/packed_arrays.h>
Public Member Functions | |
PackedArrays () | |
Creates a new empty packed array. | |
~PackedArrays () | |
Deletes a packed array. | |
bool | thread_safe () const |
Checks the thread-safety mode. More... | |
void | set_thread_safe (bool flag) |
Sets the thread-safety mode. More... | |
void | init (index_t nb_arrays, index_t Z1_block_size, bool static_mode=false) |
Initializes a packed array. More... | |
void | clear () |
Clears the packed array. More... | |
index_t | nb_arrays () const |
Get the number of arrays. More... | |
index_t | array_size (index_t array_index) const |
Gets the size of a sub-array. More... | |
void | get_array (index_t array_index, vector< index_t > &array, bool lock=true) const |
Gets a sub-array as a vector. More... | |
void | get_array (index_t array_index, index_t *array, bool lock=true) const |
Gets a sub-array. More... | |
void | set_array (index_t array_index, index_t array_size, const index_t *array_elements, bool lock=true) |
Sets a sub-array. More... | |
void | set_array (index_t array_index, const vector< index_t > &array, bool lock=true) |
Sets a sub-array from a vector. More... | |
void | resize_array (index_t array_index, index_t array_size, bool lock) |
Resizes a sub-array. More... | |
void | lock_array (index_t array_index) const |
Locks a sub-array. More... | |
void | unlock_array (index_t array_index) const |
Unlocks a sub-array. More... | |
void | show_stats () |
Displays array statistics. More... | |
Protected Member Functions | |
bool | static_mode () const |
Checks if the array is in static mode. More... | |
Efficient storage for array of arrays.
PackedArray is not a two-dimensional array, it is an array of values where each value is itself an array of GEO::index_t
. PackedArrays provides functions for efficiently setting and getting arrays by value (set_array() and get_array()).
PackedArrays tries to be as memory efficient as possible:
The idea behind PackedArrays is to be able to efficiently operate in a multi-threaded environment while limiting the locking time of the sub-arrays.
A classical read operation mode would be:
A classical write operation mode would be:
PackedArrays use SpinLockArray to lock/unlock sub-arrays in a multi-threaded environment.
Definition at line 88 of file packed_arrays.h.
Gets the size of a sub-array.
Returns the number of actual elements in the sub-array at index array_index
. This corresponds to the number of elements in the last sub-array set by set_array(). This differs from the default sub-array capacity used to preallocate the storage for the packed-array.
[in] | array_index | index of the sub-array |
Definition at line 159 of file packed_arrays.h.
void GEO::PackedArrays::clear | ( | ) |
Clears the packed array.
This frees allocated storage and resets the array as being default-constructed. Call function init() with different parameters to use it again.
Gets a sub-array.
Copies the elements of the sub-array at index array_index
to the array array
. The caller must make sure that array
has enough space for storing array_size(array_index)
elements.
The operation is atomic if parameter lock
is true
(the default) and the array is configured in thread-safety mode.
[in] | array_index | the index of the sub-array |
[out] | array | the output array of at least array_size elements. |
[in] | lock | specifies whether the operation is atomic |
|
inline |
Gets a sub-array as a vector.
Copies the elements of the sub-array at index array_index
to the vector array
.
The operation is atomic if parameter lock
is true
(the default) and the array is configured in thread-safety mode.
[in] | array_index | the index of the sub-array |
[out] | array | the output vector |
[in] | lock | specifies whether the operation is atomic |
Definition at line 177 of file packed_arrays.h.
Initializes a packed array.
This allocates storage for storing nb_arrays
with a capacity of Z1_block_size
elements of type GEO::index_t
. If parameter static_mode is true
, the overflow area is disabled and arrays are constrained to a maximum of Z1_block_size
elements.
[in] | nb_arrays | number of arrays to allocate |
[in] | Z1_block_size | default capacity of the arrays (in number of elements) |
[in] | static_mode | specifies whether the array is static mode |
|
inline |
Locks a sub-array.
This gives the calling thread exclusive access to the sub-array at index array_index
. Other threads calling this function for the same sub-array will block until the blocker thread calls unlock_array().
[in] | array_index | the index of the sub-array |
Definition at line 301 of file packed_arrays.h.
|
inline |
Get the number of arrays.
Definition at line 145 of file packed_arrays.h.
Resizes a sub-array.
Reallocates the sub-array at index array_index
to contain array_size
elements:
array_size
is greater than the original sub-array capacity, space is allocated in the overflow area to contain the extra elements,array_size
is smaller than the original sub-array capacity, any space allocated for the sub-array in the overflow area is released.The operation is atomic if parameter lock
is true
(the default) and the array is configured in thread-safety mode.
[in] | array_index | the index of the sub-array |
[in] | array_size | the new size of the sub-array |
[in] | lock | specifies whether the operation is atomic |
|
inline |
Sets a sub-array from a vector.
Copies all the elements in vector array
to the sub-array at index array_index
. If the number of elements in vector
is different than the sub-array size, the sub-array is resized (see resize_array()).
If the packed array is in static mode, setting a sub-array with a size greater than the original sub-array capacity makes the function abort().
The operation is atomic if parameter lock
is true
(the default) and the array is configured in thread-safety mode.
[in] | array_index | the index of the sub-array |
[in] | array | an array of at least array_size elements |
[in] | lock | specifies whether the operation is atomic |
Definition at line 256 of file packed_arrays.h.
void GEO::PackedArrays::set_array | ( | index_t | array_index, |
index_t | array_size, | ||
const index_t * | array_elements, | ||
bool | lock = true |
||
) |
Sets a sub-array.
Copies the first array_size
elements of the array array_elements
to the sub-array at index array_index
. If array_size
is different than the sub-array size, the sub-array is resized (see resize_array()).
If the packed array is in static mode, setting a sub-array with a size greater than the original sub-array capacity makes the function abort().
The lock
is true
(the default) and the array is configured in thread-safety mode.
[in] | array_index | the index of the sub-array |
[in] | array_size | the number of elements to copy |
[in] | array_elements | an array of at least array_size elements |
[in] | lock | specifies whether the operation is atomic |
void GEO::PackedArrays::set_thread_safe | ( | bool | flag | ) |
Sets the thread-safety mode.
[in] | flag | configures the array to be thread-safe if true . |
void GEO::PackedArrays::show_stats | ( | ) |
Displays array statistics.
This prints statistics about memory occupation in the main allocation area plus statistics about extra space allocated in the overflow area.
|
inlineprotected |
Checks if the array is in static mode.
true | if the array is in static mode |
false | otherwise |
Definition at line 334 of file packed_arrays.h.
|
inline |
Checks the thread-safety mode.
true | if the array is configured to be thread-safe |
false | otherwise |
Definition at line 105 of file packed_arrays.h.
|
inline |
Unlocks a sub-array.
Releases the lock on the sub-array at index array_index
. This gives access to the sub-array to any waiting thread.
[in] | array_index | the index of the sub-array |
Definition at line 314 of file packed_arrays.h.