vl_async_queue.h File Reference

#include "vl_async_pool.h"
#include "vl_atomic.h"
#include "vl_atomic_ptr.h"

Include dependency graph for vl_async_queue.h:

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

Go to the source code of this file.

Functions
VL_API void	vlAsyncQueueInit (vl_async_queue *queue, vl_uint16_t elementSize)
	Initializes an async queue for elements of a specified size.
VL_API void	vlAsyncQueueFree (vl_async_queue *queue)
	Frees resources held by the queue but does not deallocate the queue structure.
VL_API vl_async_queue *	vlAsyncQueueNew (vl_uint16_t elementSize)
	Allocates and initializes a new async queue on the heap.
VL_API void	vlAsyncQueueDelete (vl_async_queue *queue)
	Deletes a heap-allocated queue created with vlAsyncQueueNew.
VL_API void	vlAsyncQueueClear (vl_async_queue *queue)
	Clears the queue content and resets it to its initial dummy-node state.
VL_API void	vlAsyncQueueReset (vl_async_queue *queue)
	Resets the queue, deallocating most dynamically allocated memory.
VL_API void	vlAsyncQueuePushBack (vl_async_queue *queue, const void *value)
	Pushes a new element to the end of the queue.
VL_API vl_bool_t	vlAsyncQueuePopFront (vl_async_queue *queue, void *result)
	Pops an element from the front of the queue.

Function Documentation

vlAsyncQueueClear()

VL_API void vlAsyncQueueClear

(

vl_async_queue *

queue

)

Clears the queue content and resets it to its initial dummy-node state.

Parameters

queue

Pointer to the queue.

Note

Does not free memory but allows memory to be reused.

Not safe to call concurrently with push/pop operations; external synchronization required.

Here is the call graph for this function:

vlAsyncQueueDelete()

VL_API void vlAsyncQueueDelete

(

vl_async_queue *

queue

)

Deletes a heap-allocated queue created with vlAsyncQueueNew.

Contract

• Ownership: Releases ownership and all resources.
• Lifetime: The queue pointer becomes invalid.
• Thread Safety: Not thread-safe.
• Nullability: Safe to call with NULL (due to free and vlAsyncQueueFree should be made safe or checked). Wait, vlAsyncQueueFree calls vlAsyncPoolFree which might not be safe.
• Error Conditions: None.
• Undefined Behavior: Double deletion.
• Memory Allocation Expectations: Frees all heap memory associated with the queue.
• Return-value Semantics: None (void).

Parameters

queue

Pointer to the queue to be deleted.

Here is the call graph for this function:

Here is the caller graph for this function:

vlAsyncQueueFree()

VL_API void vlAsyncQueueFree

(

vl_async_queue *

queue

)

Frees resources held by the queue but does not deallocate the queue structure.

Contract

• Ownership: Releases internal resources.
• Lifetime: The queue structure remains but its contents are invalid.
• Thread Safety: Not thread-safe.
• Nullability: queue must not be NULL.
• Error Conditions: None.
• Undefined Behavior: Calling on a queue that is being used by other threads.
• Memory Allocation Expectations: Deallocates internal pool blocks.
• Return-value Semantics: None (void).

Parameters

queue

Pointer to an initialized vl_async_queue.

Here is the call graph for this function:

Here is the caller graph for this function:

vlAsyncQueueInit()

VL_API void vlAsyncQueueInit	(	vl_async_queue *	queue,
		vl_uint16_t	elementSize
	)

Initializes an async queue for elements of a specified size.

Contract

• Ownership: The caller provides the queue memory.
• Lifetime: The queue must be freed with vlAsyncQueueFree before its memory is reclaimed.
• Thread Safety: Not thread-safe for the same queue instance.
• Nullability: queue must not be NULL.
• Error Conditions: May crash if queue is NULL.
• Undefined Behavior: Calling on an already initialized queue without freeing it first.
• Memory Allocation Expectations: Allocates initial internal pool blocks.
• Return-value Semantics: None (void).

Parameters

queue	Pointer to an uninitialized vl_async_queue structure.
elementSize	Size in bytes of each element stored in the queue.

Here is the call graph for this function:

Here is the caller graph for this function:

vlAsyncQueueNew()

VL_API vl_async_queue * vlAsyncQueueNew

(

vl_uint16_t

elementSize

)

Allocates and initializes a new async queue on the heap.

Contract

• Ownership: The caller owns the returned vl_async_queue pointer and is responsible for calling vlAsyncQueueDelete.
• Lifetime: The queue remains valid until vlAsyncQueueDelete.
• Thread Safety: This function is thread-safe.
• Nullability: Returns NULL if allocation fails.
• Error Conditions: Returns NULL if heap allocation for the queue structure or initial internal blocks fails.
• Undefined Behavior: None.
• Memory Allocation Expectations: Allocates the queue structure and initial pool blocks on the heap.
• Return-value Semantics: Returns a pointer to the new queue, or NULL on failure.

Parameters

elementSize

Size in bytes of each element stored in the queue.

Returns

Pointer to the newly allocated vl_async_queue.

Here is the call graph for this function:

Here is the caller graph for this function:

vlAsyncQueuePopFront()

VL_API vl_bool_t vlAsyncQueuePopFront	(	vl_async_queue *	queue,
		void *	result
	)

Pops an element from the front of the queue.

Contract

• Ownership: Copies the popped data into result.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (lock-free MPMC).
• Nullability: queue and result must not be NULL.
• Error Conditions: Returns VL_FALSE if the queue is empty.
• Undefined Behavior: Passing NULL.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns VL_TRUE if an element was popped, VL_FALSE if the queue was empty.

Parameters

queue	Pointer to the queue.
result	Pointer to the buffer where the popped value will be written (must be elementSize bytes).

Returns

VL_TRUE if an element was dequeued, VL_FALSE if the queue was empty.

Note

Safe to call concurrently from multiple threads.

Here is the call graph for this function:

vlAsyncQueuePushBack()

VL_API void vlAsyncQueuePushBack	(	vl_async_queue *	queue,
		const void *	value
	)

Pushes a new element to the end of the queue.

Contract

• Ownership: The queue copies the data from value.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (lock-free MPMC).
• Nullability: queue and value must not be NULL.
• Error Conditions: May allocate new blocks if the internal pool is empty.
• Undefined Behavior: Passing NULL.
• Memory Allocation Expectations: May allocate more memory for the internal pool if needed.
• Return-value Semantics: None (void).

Parameters

queue	Pointer to the queue.
value	Pointer to the data to enqueue (must be elementSize bytes).

Note

Safe to call concurrently from multiple threads.

Here is the call graph for this function:

Here is the caller graph for this function:

vlAsyncQueueReset()

VL_API void vlAsyncQueueReset

(

vl_async_queue *

queue

)

Resets the queue, deallocating most dynamically allocated memory.

Parameters

queue

Pointer to the queue.

Note

Leaves the queue in an initialized but empty state.

Not safe to call concurrently with push/pop operations; external synchronization required.

Here is the call graph for this function: