Scroll to navigation

sds_lqueue(3) dirsrv sds_lqueue(3)

NAME

sds_lqueue - SDS Lock Free Queue

SYNOPSIS

Typedefs


typedef struct _sds_tqueue sds_lqueue

Functions


sds_result sds_lqueue_init (sds_lqueue **q_ptr, void(*value_free_fn)(void *value))
sds_result sds_lqueue_tprep (sds_lqueue *q)
sds_result sds_lqueue_enqueue (sds_lqueue *q, void *elem)
sds_result sds_lqueue_dequeue (sds_lqueue *q, void **elem)
sds_result sds_lqueue_destroy (sds_lqueue *q)

Detailed Description

Thread safe lock free queue. Falls back to platform mutex if cpu intrinsics are not present.

Typedef Documentation

typedef struct _sds_tqueue sds_lqueue

Type definition of lock free queue to the mutex queue in the case that cpu intrinsics are not available, or the operating system is unsupported.

Function Documentation

sds_result sds_lqueue_dequeue (sds_lqueue * q, void ** elem)

Dequeue an item from the head of the queue. Equivalent to 'pop'. The safety of this operation is implicit, you do not need any other mutexes to protect this operation.

Parameters

q The struct pointer to the queue you wish to pop from.
elem a pointer to a location which will be over-ridden with the data that is dequeued. This may be NULLed, even during an error.

Return values

sds_result to indicate the status of the operation.

sds_result sds_lqueue_destroy (sds_lqueue * q)

Indicate you are complete with the queue. Free and delete any remaining internal structures, and free and still queued nodes. You must always call this function to dispose of this structure.

Important to note, is that all thread consumers of this queue must be stopped before you call lqueue destroy. This is your responsibility to ensure this.

Parameters

q The struct pointer to the queue you wish to dispose of.

Return values

sds_result to indicate the status of the operation.

sds_result sds_lqueue_enqueue (sds_lqueue * q, void * elem)

Enqueue an item to the tail of this queue. Equivalent to 'push'. The safety of this operation is implicit, you do not need any other mutexes to protect this operation.

Parameters

q The struct pointer to the queue you wish to push to.
elem The data to enqueue.

Return values

sds_result to indicate the status of the operation.

sds_result sds_lqueue_init (sds_lqueue ** q_ptr, void(*)(void *value) value_free_fn)

Initialise a queue suitable for access across multiple threads. Free function must be set. This utilises hardware intrinsics to provide atomicity that may be faster in highly contended applications. Use this structure in place of a tqueue only if you know that content of the queue will be high.

Parameters

q_ptr A pointer to the struct pointer you wish to allocate. This may be on the heap or stack.
value_free_fn A function pointer to free values that are enqueued to this structure.

Return values

sds_result to indicate the status of the operation.

sds_result sds_lqueue_tprep (sds_lqueue * q)

Initialise this thread ready to use the lqueue. This is critical, and accessing the queue without calling tprep may result in undefined behaviour.

Author

Generated automatically by Doxygen for dirsrv from the source code.

Fri May 31 2024 Version 2.4.5