Geogram  Version 1.9.1
A programming library of geometric algorithms
GEO::PackedArrays Class Reference

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...
 

Detailed Description

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:

  • each sub-array is configured with a default capacity allowing to allocate a single fixed size memory area for all sub-arrays
  • sub-arrays can be resized individually using an overflow area by calling resize_array().

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:

  • lock a sub-array
  • read the sub-array by value
  • unlock the sub-array
  • access sub-array elements

A classical write operation mode would be:

  • prepare or modify sub-array elements
  • lock a sub-array
  • write sub-the array by value
  • unlock the sub-array

PackedArrays use SpinLockArray to lock/unlock sub-arrays in a multi-threaded environment.

Definition at line 88 of file packed_arrays.h.

Member Function Documentation

◆ array_size()

index_t GEO::PackedArrays::array_size ( index_t  array_index) const
inline

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.

Parameters
[in]array_indexindex of the sub-array
Returns
the actual size of the sub-array elements

Definition at line 159 of file packed_arrays.h.

◆ clear()

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.

◆ get_array() [1/2]

void GEO::PackedArrays::get_array ( index_t  array_index,
index_t array,
bool  lock = true 
) const

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.

Parameters
[in]array_indexthe index of the sub-array
[out]arraythe output array of at least array_size elements.
[in]lockspecifies whether the operation is atomic

◆ get_array() [2/2]

void GEO::PackedArrays::get_array ( index_t  array_index,
vector< index_t > &  array,
bool  lock = true 
) const
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.

Parameters
[in]array_indexthe index of the sub-array
[out]arraythe output vector
[in]lockspecifies whether the operation is atomic

Definition at line 177 of file packed_arrays.h.

◆ init()

void GEO::PackedArrays::init ( index_t  nb_arrays,
index_t  Z1_block_size,
bool  static_mode = false 
)

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.

Parameters
[in]nb_arraysnumber of arrays to allocate
[in]Z1_block_sizedefault capacity of the arrays (in number of elements)
[in]static_modespecifies whether the array is static mode

◆ lock_array()

void GEO::PackedArrays::lock_array ( index_t  array_index) const
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().

Parameters
[in]array_indexthe index of the sub-array

Definition at line 301 of file packed_arrays.h.

◆ nb_arrays()

index_t GEO::PackedArrays::nb_arrays ( ) const
inline

Get the number of arrays.

Returns
the number of arrays in this packed array

Definition at line 145 of file packed_arrays.h.

◆ resize_array()

void GEO::PackedArrays::resize_array ( index_t  array_index,
index_t  array_size,
bool  lock 
)

Resizes a sub-array.

Reallocates the sub-array at index array_index to contain array_size elements:

  • if array_size is greater than the original sub-array capacity, space is allocated in the overflow area to contain the extra elements,
  • if 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.

Parameters
[in]array_indexthe index of the sub-array
[in]array_sizethe new size of the sub-array
[in]lockspecifies whether the operation is atomic

◆ set_array() [1/2]

void GEO::PackedArrays::set_array ( index_t  array_index,
const vector< index_t > &  array,
bool  lock = true 
)
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.

Parameters
[in]array_indexthe index of the sub-array
[in]arrayan array of at least array_size elements
[in]lockspecifies whether the operation is atomic

Definition at line 256 of file packed_arrays.h.

◆ set_array() [2/2]

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.

Parameters
[in]array_indexthe index of the sub-array
[in]array_sizethe number of elements to copy
[in]array_elementsan array of at least array_size elements
[in]lockspecifies whether the operation is atomic

◆ set_thread_safe()

void GEO::PackedArrays::set_thread_safe ( bool  flag)

Sets the thread-safety mode.

Parameters
[in]flagconfigures the array to be thread-safe if true.

◆ show_stats()

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.

◆ static_mode()

bool GEO::PackedArrays::static_mode ( ) const
inlineprotected

Checks if the array is in static mode.

Return values
trueif the array is in static mode
falseotherwise

Definition at line 334 of file packed_arrays.h.

◆ thread_safe()

bool GEO::PackedArrays::thread_safe ( ) const
inline

Checks the thread-safety mode.

Return values
trueif the array is configured to be thread-safe
falseotherwise

Definition at line 105 of file packed_arrays.h.

◆ unlock_array()

void GEO::PackedArrays::unlock_array ( index_t  array_index) const
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.

Parameters
[in]array_indexthe index of the sub-array

Definition at line 314 of file packed_arrays.h.


The documentation for this class was generated from the following file: