InlineVarLenEntryQueue C API

Classes
struct	pw_InlineVarLenEntryQueue_Iterator
struct	pw_InlineVarLenEntryQueue_Entry

Macros
#define	PW_VARIABLE_LENGTH_ENTRY_QUEUE_DECLARE(variable, max_size_bytes)
#define	PW_VARIABLE_LENGTH_ENTRY_QUEUE_HEADER_SIZE_UINT32   (3)

Typedefs
typedef uint32_t *	pw_InlineVarLenEntryQueue_Handle
typedef const uint32_t *	pw_InlineVarLenEntryQueue_ConstHandle

Functions
static void	pw_InlineVarLenEntryQueue_Init (uint32_t array[], size_t array_size_uint32)
static void	pw_InlineVarLenEntryQueue_Clear (pw_InlineVarLenEntryQueue_Handle queue)
	Empties the queue.
void	pw_InlineVarLenEntryQueue_Push (pw_InlineVarLenEntryQueue_Handle queue, const void *data, uint32_t data_size_bytes)
bool	pw_InlineVarLenEntryQueue_TryPush (pw_InlineVarLenEntryQueue_Handle queue, const void *data, const uint32_t data_size_bytes)
void	pw_InlineVarLenEntryQueue_PushOverwrite (pw_InlineVarLenEntryQueue_Handle queue, const void *data, uint32_t data_size_bytes)
void	pw_InlineVarLenEntryQueue_Pop (pw_InlineVarLenEntryQueue_Handle queue)
static pw_InlineVarLenEntryQueue_Iterator	pw_InlineVarLenEntryQueue_Begin (pw_InlineVarLenEntryQueue_ConstHandle queue)
	Returns an iterator to the start of the InlineVarLenEntryQueue.
static pw_InlineVarLenEntryQueue_Iterator	pw_InlineVarLenEntryQueue_End (pw_InlineVarLenEntryQueue_ConstHandle queue)
	Returns an iterator that points past the end of the queue.
void	pw_InlineVarLenEntryQueue_Iterator_Advance (pw_InlineVarLenEntryQueue_Iterator *iterator)
static bool	pw_InlineVarLenEntryQueue_Iterator_Equal (const pw_InlineVarLenEntryQueue_Iterator *lhs, const pw_InlineVarLenEntryQueue_Iterator *rhs)
	Compares two iterators for equality.
pw_InlineVarLenEntryQueue_Entry	pw_InlineVarLenEntryQueue_GetEntry (const pw_InlineVarLenEntryQueue_Iterator *iterator)
	Dereferences an iterator, loading the entry it points to.
uint32_t	pw_InlineVarLenEntryQueue_Entry_Copy (const pw_InlineVarLenEntryQueue_Entry *entry, void *dest, uint32_t count)
static uint8_t	pw_InlineVarLenEntryQueue_Entry_At (const pw_InlineVarLenEntryQueue_Entry *entry, size_t index)
uint32_t	pw_InlineVarLenEntryQueue_Size (pw_InlineVarLenEntryQueue_ConstHandle queue)
static uint32_t	pw_InlineVarLenEntryQueue_MaxSize (pw_InlineVarLenEntryQueue_ConstHandle queue)
uint32_t	pw_InlineVarLenEntryQueue_SizeBytes (pw_InlineVarLenEntryQueue_ConstHandle queue)
static uint32_t	pw_InlineVarLenEntryQueue_MaxSizeBytes (pw_InlineVarLenEntryQueue_ConstHandle queue)
static uint32_t	pw_InlineVarLenEntryQueue_RawStorageSizeBytes (pw_InlineVarLenEntryQueue_ConstHandle queue)
static bool	pw_InlineVarLenEntryQueue_Empty (pw_InlineVarLenEntryQueue_ConstHandle queue)

Detailed Description

Macro Definition Documentation

PW_VARIABLE_LENGTH_ENTRY_QUEUE_DECLARE

#define PW_VARIABLE_LENGTH_ENTRY_QUEUE_DECLARE	(		variable,
			max_size_bytes
	)

Value:

  uint32_t variable[PW_VARIABLE_LENGTH_ENTRY_QUEUE_HEADER_SIZE_UINT32 +  \
                    _PW_VAR_QUEUE_DATA_SIZE_UINT32(max_size_bytes)] = {  \
      _PW_VAR_QUEUE_DATA_SIZE_BYTES(max_size_bytes), /*head=*/0u, /*tail=*/0u}

Declares and initializes a InlineVarLenEntryQueue that can hold up to max_size_bytes bytes. max_size_bytes is the largest supported size for a single entry; attempting to store larger entries is invalid and will fail an assertion.

Parameters

variable	variable name for the queue
max_size_bytes	the capacity of the queue

PW_VARIABLE_LENGTH_ENTRY_QUEUE_HEADER_SIZE_UINT32

#define PW_VARIABLE_LENGTH_ENTRY_QUEUE_HEADER_SIZE_UINT32   (3)

The size of the InlineVarLenEntryQueue header, in uint32_t elements. This header stores the buffer length and head and tail offsets.

The underlying uint32_t array of a InlineVarLenEntryQueue must be larger than this size.

Typedef Documentation

pw_InlineVarLenEntryQueue_Handle

typedef uint32_t* pw_InlineVarLenEntryQueue_Handle

Handle that refers to a InlineVarLenEntryQueue. In memory, the queue is a uint32_t array.

Function Documentation

pw_InlineVarLenEntryQueue_Empty()

static bool pw_InlineVarLenEntryQueue_Empty ( pw_InlineVarLenEntryQueue_ConstHandle  queue )

inlinestatic

Returns true if the InlineVarLenEntryQueue is empty, false if it has at least one entry.

pw_InlineVarLenEntryQueue_Entry_At()

static uint8_t pw_InlineVarLenEntryQueue_Entry_At ( const pw_InlineVarLenEntryQueue_Entry *  entry, size_t  index  )

inlinestatic

Returns the byte at the specified index in the entry. Asserts if index is out-of-bounds.

pw_InlineVarLenEntryQueue_Entry_Copy()

uint32_t pw_InlineVarLenEntryQueue_Entry_Copy	(	const pw_InlineVarLenEntryQueue_Entry *	entry,
		void *	dest,
		uint32_t	count
	)

Copies the contents of the entry to the provided buffer. The entry may be split into two regions; this serializes it into one buffer.

Parameters

entry	The entry whose contents to copy
dest	The buffer into which to copy the serialized entry
count	Copy up to this many bytes; must not be larger than the dest buffer, but may be larger than the entry

pw_InlineVarLenEntryQueue_Init()

static void pw_InlineVarLenEntryQueue_Init ( uint32_t  array[], size_t  array_size_uint32  )

inlinestatic

Initializes a InlineVarLenEntryQueue in place in a uint32_t array. The array MUST be larger than

embed:rst:inline :c:macro:`PW_VARIABLE_LENGTH_ENTRY_QUEUE_HEADER_SIZE_UINT32` 

(3) elements.

pw_InlineVarLenEntryQueue_Iterator_Advance()

void pw_InlineVarLenEntryQueue_Iterator_Advance

(

pw_InlineVarLenEntryQueue_Iterator *

iterator

)

Advances an iterator to point to the next entry in the queue. It is invalid to call Advance on an iterator equal to the End iterator.

pw_InlineVarLenEntryQueue_MaxSize()

static uint32_t pw_InlineVarLenEntryQueue_MaxSize ( pw_InlineVarLenEntryQueue_ConstHandle  queue )

inlinestatic

Returns the maximum number of entries in the queue. This is only attainable if all entries are empty.

pw_InlineVarLenEntryQueue_MaxSizeBytes()

static uint32_t pw_InlineVarLenEntryQueue_MaxSizeBytes ( pw_InlineVarLenEntryQueue_ConstHandle  queue )

inlinestatic

Returns the the maximum number of bytes that can be stored in the queue. This is largest possible value of size_bytes(), and the size of the largest single entry that can be stored in this queue. Attempting to store a larger entry is invalid and results in a crash.

pw_InlineVarLenEntryQueue_Pop()

void pw_InlineVarLenEntryQueue_Pop

(

pw_InlineVarLenEntryQueue_Handle

queue

)

Removes the first entry from queue.

Precondition

The queue MUST have at least one entry.

pw_InlineVarLenEntryQueue_Push()

void pw_InlineVarLenEntryQueue_Push	(	pw_InlineVarLenEntryQueue_Handle	queue,
		const void *	data,
		uint32_t	data_size_bytes
	)

Appends an entry to the end of the queue.

Precondition

The entry MUST NOT be larger than max_size_bytes().

There must be sufficient space in the queue for this entry.

pw_InlineVarLenEntryQueue_PushOverwrite()

void pw_InlineVarLenEntryQueue_PushOverwrite	(	pw_InlineVarLenEntryQueue_Handle	queue,
		const void *	data,
		uint32_t	data_size_bytes
	)

Appends an entry to the end of the queue, removing entries with Pop as necessary to make room. Calling this function drops old entries to make room for new; call try_push() to drop new entries instead.

Precondition

The entry MUST NOT be larger than max_size_bytes().

pw_InlineVarLenEntryQueue_RawStorageSizeBytes()

static uint32_t pw_InlineVarLenEntryQueue_RawStorageSizeBytes ( pw_InlineVarLenEntryQueue_ConstHandle  queue )

inlinestatic

Returns the size of the raw underlying InlineVarLenEntryQueue storage. This size may be used to copy a InlineVarLenEntryQueue into another 32-bit aligned memory location.

pw_InlineVarLenEntryQueue_Size()

uint32_t pw_InlineVarLenEntryQueue_Size

(

pw_InlineVarLenEntryQueue_ConstHandle

queue

)

Returns the number of variable-length entries in the queue. This is O(n) in the number of entries in the queue.

pw_InlineVarLenEntryQueue_SizeBytes()

uint32_t pw_InlineVarLenEntryQueue_SizeBytes

(

pw_InlineVarLenEntryQueue_ConstHandle

queue

)

Returns the combined size in bytes of all entries in the queue, excluding metadata. This is O(n) in the number of entries in the queue.

pw_InlineVarLenEntryQueue_TryPush()

bool pw_InlineVarLenEntryQueue_TryPush	(	pw_InlineVarLenEntryQueue_Handle	queue,
		const void *	data,
		const uint32_t	data_size_bytes
	)

Appends an entry to the end of the queue, but only if there is sufficient space for it.

Returns

true if the data was added to the queue; false if it did not fit

Precondition

The entry MUST NOT be larger than max_size_bytes().