vl_async_pool.h File Reference

#include "vl_atomic.h"
#include "vl_atomic_ptr.h"
#include "vl_memory.h"

Include dependency graph for vl_async_pool.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
VL_API void	vlAsyncPoolInitAligned (vl_async_pool *pool, vl_uint16_t elementSize, vl_uint16_t elementAlign)
	Initializes the specified async pool, with the specified alignment.
VL_API void	vlAsyncPoolFree (vl_async_pool *pool)
	Frees the specified async pool, and all associated memory.
VL_API vl_async_pool *	vlAsyncPoolNewAligned (vl_uint16_t elementSize, vl_uint16_t elementAlign)
	Allocates and initializes a new async pool, and specified alignment.
VL_API void	vlAsyncPoolDelete (vl_async_pool *pool)
	Deinitializes and deletes the specified async pool, and all associated memory.
VL_API void	vlAsyncPoolReset (vl_async_pool *pool)
	Resets the specified async pool, returning it to its state when it was first initialized.
VL_API void	vlAsyncPoolClear (vl_async_pool *pool)
	Resets the state of all blocks and the pool, retaining memory but invalidating taken elements.
VL_API void *	vlAsyncPoolTake (vl_async_pool *pool)
	Takes an element from the specified async pool.
VL_API void	vlAsyncPoolReturn (vl_async_pool *pool, void *element)
	Returns an element to the specified async pool.

Function Documentation

vlAsyncPoolClear()

VL_API void vlAsyncPoolClear

(

vl_async_pool *

pool

)

Resets the state of all blocks and the pool, retaining memory but invalidating taken elements.

This does not free any associated memory.

Warning

This will invalidate all elements taken prior to this call. Manual synchronization is highly recommended.

Parameters

pool	pointer to the async pool to clear

Here is the caller graph for this function:

vlAsyncPoolDelete()

VL_API void vlAsyncPoolDelete

(

vl_async_pool *

pool

)

Deinitializes and deletes the specified async pool, and all associated memory.

The specified pool must have been initialized via vlAsyncPoolNew.

Warning

This will invalidate all elements taken prior to this call. Manual synchronization is highly recommended.

See also

vlAsyncPoolNew

Parameters

pool	pointer to async pool to delete

Here is the call graph for this function:

vlAsyncPoolFree()

VL_API void vlAsyncPoolFree

(

vl_async_pool *

pool

)

Frees the specified async pool, and all associated memory.

The pool must have been initialized via vlAsyncPoolInit.

Warning

This will invalidate all elements taken prior to this call. Manual synchronization is highly recommended.

See also

vlAsyncPoolInit

Parameters

pool

Here is the call graph for this function:

Here is the caller graph for this function:

vlAsyncPoolInitAligned()

VL_API void vlAsyncPoolInitAligned	(	vl_async_pool *	pool,
		vl_uint16_t	elementSize,
		vl_uint16_t	elementAlign
	)

Initializes the specified async pool, with the specified alignment.

The pool must be later freed via vlAsyncPoolFree.

Contract

• Ownership: The caller provides the pool memory. The pool manages its own internal blocks.
• Lifetime: The pool remains valid until vlAsyncPoolFree or vlAsyncPoolDelete.
• Thread Safety: Not thread-safe for the same pool instance.
• Nullability: pool must not be NULL.
• Error Conditions: None.
• Undefined Behavior: Passing NULL.
• Memory Allocation Expectations: Does not allocate immediately; allocation is deferred until the first element is taken.
• Return-value Semantics: None (void).

Warning

alignment must be a power of 2.

See also

vlAsyncPoolFree

Parameters

pool	pointer to pool that will be initialized
elementSize	total size of a single element, in bytes.
elementAlign	byte alignment of pool elements.

Here is the caller graph for this function:

vlAsyncPoolNewAligned()

VL_API vl_async_pool * vlAsyncPoolNewAligned	(	vl_uint16_t	elementSize,
		vl_uint16_t	elementAlign
	)

Allocates and initializes a new async pool, and specified alignment.

The specified pool must later be deleted via vlAsyncPoolDelete.

Warning

alignment must be a power of 2.

See also

vlAsyncPoolDelete

Parameters

elementSize	total size of a single element, in bytes.
elementAlign	byte alignment of pool elements.

Returns

pointer to newly allocated async pool.

Here is the call graph for this function:

vlAsyncPoolReset()

VL_API void vlAsyncPoolReset

(

vl_async_pool *

pool

)

Resets the specified async pool, returning it to its state when it was first initialized.

This frees all allocated blocks of nodes up to the first.

Warning

This will invalidate all elements taken prior to this call. Manual synchronization is highly recommended.

Parameters

pool	pointer to the async pool to reset

Here is the call graph for this function:

Here is the caller graph for this function:

vlAsyncPoolReturn()

VL_API void vlAsyncPoolReturn	(	vl_async_pool *	pool,
		void *	element
	)

Returns an element to the specified async pool.

Parameters

pool	pointer to async pool
element	pointer to returned element

Complexity of O(1) constant.

Here is the caller graph for this function:

vlAsyncPoolTake()

VL_API void * vlAsyncPoolTake

(

vl_async_pool *

pool

)

Takes an element from the specified async pool.

Contract

• Ownership: The pool retains ownership of the underlying memory. The caller receives a pointer to an element that must eventually be returned via vlAsyncPoolReturn.
• Lifetime: The returned pointer is valid until it is returned to the pool or the pool is cleared/deleted.
• Thread Safety: Thread-safe (lock-free).
• Nullability: Returns NULL if a new block cannot be allocated when the pool is empty.
• Error Conditions: Returns NULL on heap allocation failure for new blocks.
• Undefined Behavior: Passing NULL.
• Memory Allocation Expectations: May allocate a new block of elements on the heap if the pool is empty.
• Return-value Semantics: Returns a pointer to an available element, or NULL on failure.

Parameters

pool	pointer to async pool

Complexity of O(1) constant.

Returns

pointer to taken element

Here is the caller graph for this function: