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_index index 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_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

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

◆ 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_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

◆ 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_index the 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_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

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

◆ 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_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

◆ set_thread_safe()

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

Sets the thread-safety mode.

Parameters

[in] flag configures 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

true	if the array is in static mode
false	otherwise

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

true	if the array is configured to be thread-safe
false	otherwise

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_index the 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:

geogram/basic/packed_arrays.h

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ array_size()

◆ clear()

◆ get_array() [1/2]

◆ get_array() [2/2]

◆ init()

◆ lock_array()

◆ nb_arrays()

◆ resize_array()

◆ set_array() [1/2]

◆ set_array() [2/2]

◆ set_thread_safe()

◆ show_stats()

◆ static_mode()

◆ thread_safe()

◆ unlock_array()