queue.h File Reference

Memory queue function definitions. More...

#include "common.h"

Go to the source code of this file.

Data Structures
struct	qsc_queue_state
	Contains the queue context state. More...

Macros
#define	QSC_QUEUE_ALIGNMENT   64ULL
	The internal memory alignment constant.
#define	QSC_QUEUE_MAX_DEPTH   64ULL
	The maximum queue depth.

Functions
QSC_EXPORT_API void	qsc_queue_dispose (qsc_queue_state *ctx)
	Destroy the queue state.
QSC_EXPORT_API void	qsc_queue_flush (qsc_queue_state *ctx, uint8_t *output)
	Flush the content of the queue to an array.
QSC_EXPORT_API void	qsc_queue_initialize (qsc_queue_state *ctx, size_t depth, size_t width)
	Initialize the queue state.
QSC_EXPORT_API size_t	qsc_queue_items (const qsc_queue_state *ctx)
	Get the number of items in the queue.
QSC_EXPORT_API bool	qsc_queue_full (const qsc_queue_state *ctx)
	Get the full status from the queue.
QSC_EXPORT_API bool	qsc_queue_empty (const qsc_queue_state *ctx)
	Get the empty status from the queue.
QSC_EXPORT_API uint64_t	qsc_queue_pop (qsc_queue_state *ctx, uint8_t *output, size_t otplen)
	Returns the first member of the queue, and erases that item from the queue.
QSC_EXPORT_API void	qsc_queue_push (qsc_queue_state *ctx, const uint8_t *input, size_t inplen, uint64_t tag)
	Add an item to the queue.

Detailed Description

Memory queue function definitions.

The queue implementation provides functions for managing a memory queue that stores items along with associated 64-bit tags. The queue supports operations to push items onto the queue, pop items off the queue, and flush the queue contents into a contiguous byte array for serialization or further processing. Additionally, the header provides functions to check if the queue is full or empty, and to retrieve the current number of items in the queue. The queue is implemented as a contiguous memory block with fixed capacity, ensuring predictable memory usage and performance.

Example Usage:

#include "queue.h"
 
qsc_queue_state collection;
// Initialize the queue with a depth of 32 items, each 64 bytes wide.
qsc_queue_initialize(&collection, 32, 64);
 
uint8_t sample_item[64] = { item data };
uint64_t tag = 123456789;
 
// Push the item into the queue.
qsc_queue_push(&collection, sample_item, sizeof(sample_item), tag);
 
// Check if the queue is empty.
if (!qsc_queue_empty(&collection))
{
    uint8_t retrieved[64];
    uint64_t retrieved_tag = qsc_queue_pop(&collection, retrieved, sizeof(retrieved));
}
 
// Serialize the queue into an array.
size_t serialized_size = qsc_queue_size(&collection);
uint8_t* serialized = malloc(serialized_size);
qsc_queue_serialize(serialized, &collection);
 
// Dispose the collection.
qsc_queue_dispose(&collection);
free(serialized);

Function Documentation

qsc_queue_dispose()

QSC_EXPORT_API void qsc_queue_dispose

(

qsc_queue_state *

ctx

)

Destroy the queue state.

Parameters

ctx	[struct] A pointer to the queue state structure.

qsc_queue_empty()

QSC_EXPORT_API bool qsc_queue_empty

(

const qsc_queue_state *

ctx

)

Get the empty status from the queue.

Parameters

ctx	[const qsc_queue_state*] A pointer to the queue state structure.

Returns

[bool] Returns true if the queue is empty.

qsc_queue_flush()

QSC_EXPORT_API void qsc_queue_flush	(	qsc_queue_state *	ctx,
		uint8_t *	output )

Flush the content of the queue to an array.

Parameters

ctx	[qsc_queue_state*] A pointer to the queue state structure.
output	[uint8_t*] A pointer to the array receiving the queue items.

qsc_queue_full()

QSC_EXPORT_API bool qsc_queue_full

(

const qsc_queue_state *

ctx

)

Get the full status from the queue.

Parameters

ctx	[const qsc_queue_state*] A pointer to the queue state structure.

Returns

[bool] Returns true if the queue is full.

qsc_queue_initialize()

QSC_EXPORT_API void qsc_queue_initialize	(	qsc_queue_state *	ctx,
		size_t	depth,
		size_t	width )

Initialize the queue state.

Parameters

ctx	[qsc_queue_state*] A pointer to the queue state structure.
depth	[size_t] The number of queue items to initialize, maximum is QSC_QUEUE_MAX_DEPTH.
width	[size_t] The maximum size of each queue item in bytes.

qsc_queue_items()

QSC_EXPORT_API size_t qsc_queue_items

(

const qsc_queue_state *

ctx

)

Get the number of items in the queue.

Parameters

ctx	[const qsc_queue_state*] A pointer to the queue state structure.

Returns

[size_t] The number of items in the queue.

qsc_queue_pop()

QSC_EXPORT_API uint64_t qsc_queue_pop	(	qsc_queue_state *	ctx,
		uint8_t *	output,
		size_t	otplen )

Returns the first member of the queue, and erases that item from the queue.

Parameters

ctx	[qsc_queue_state*] A pointer to the queue state structure.
output	[uint8_t*] A pointer to the array receiving the queue item.
otplen	[size_t] The number of bytes to copy from the queue item.

Returns

[uint64_t] The tag associated with the removed item.

qsc_queue_push()

QSC_EXPORT_API void qsc_queue_push	(	qsc_queue_state *	ctx,
		const uint8_t *	input,
		size_t	inplen,
		uint64_t	tag )

Add an item to the queue.

Parameters

ctx	[qsc_queue_state*] A pointer to the queue state structure.
input	[uint8_t*] A pointer to the array item to be added to the queue.
inplen	[size_t] The byte size of the queue item to be added.
tag	[uint64_t] The tag associated with the item.