vl_async_queue.h File Reference

#include "vl_atomic.h"
#include "vl_atomic_ptr.h"
#include "vl_async_pool.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.

Data Structures
struct	vl_async_queue
	Multi-Producer, Multi-Consumer (MPMC) Lock-Free Queue. More...

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

---

Data Structure Documentation

vl_async_queue

struct vl_async_queue

Multi-Producer, Multi-Consumer (MPMC) Lock-Free Queue.

This structure implements a fully atomic, non-blocking concurrent queue designed to support multiple producers and multiple consumers safely.

The queue is based on the Michael & Scott lock-free concurrent queue algorithm, which ensures high throughput and fairness without requiring locks.

The queue internally manages memory using vl_async_pool for efficient node allocation and reclamation.

Note

All queue operations are thread-safe and can be called concurrently from multiple threads without external synchronization.

The size field provides a current estimate of the queue length, but may be temporarily inconsistent due to concurrent modifications.

See also

https://www.cs.rochester.edu/u/scott/papers/1996_PODC_queues.pdf

Collaboration diagram for vl_async_queue:

Data Fields
vl_async_pool	elements	Underlying memory pool for queue nodes
vl_uint16_t	elementSize	Size in bytes of each element stored in the queue
vl_atomic_ptr	head	Atomic pointer to the queue head node (dummy node)
vl_atomic_uint32_t	size	Approximate count of elements in the queue
vl_atomic_ptr	tail	Atomic pointer to the queue tail node

Function Documentation

vlAsyncQueueClear()

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()

void vlAsyncQueueDelete

(

vl_async_queue *

queue

)

Deletes a heap-allocated queue created with vlAsyncQueueNew.

Parameters

queue

Pointer to the queue to be deleted.

Here is the call graph for this function:

vlAsyncQueueFree()

void vlAsyncQueueFree

(

vl_async_queue *

queue

)

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

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()

void vlAsyncQueueInit	(	vl_async_queue *	queue,
		vl_uint16_t	elementSize )

Initializes an async queue for elements of a specified size.

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_async_queue * vlAsyncQueueNew

(

vl_uint16_t

elementSize

)

Allocates and initializes a new async queue on the heap.

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:

vlAsyncQueuePopFront()

vl_bool_t vlAsyncQueuePopFront	(	vl_async_queue *	queue,
		void *	result )

Pops an element from the front of the queue.

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()

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

Pushes a new element to the end of the queue.

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:

vlAsyncQueueReset()

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: