Overview

Macros
#define	PW_VARIABLE_LENGTH_ENTRY_QUEUE_DECLARE(variable, max_size_bytes)

Typedefs
typedef uint32_t *	pw_InlineVarLenEntryQueue_Handle

typedef const uint32_t *	pw_InlineVarLenEntryQueue_ConstHandle

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

pw_InlineVarLenEntryQueue_Iterator	pw_InlineVarLenEntryQueue_Begin (pw_InlineVarLenEntryQueue_Handle queue)
	Returns an iterator to the start of the `queue`.

pw_InlineVarLenEntryQueue_ConstIterator	pw_InlineVarLenEntryQueue_ConstBegin (pw_InlineVarLenEntryQueue_ConstHandle queue)

pw_InlineVarLenEntryQueue_Iterator	pw_InlineVarLenEntryQueue_End (pw_InlineVarLenEntryQueue_Handle queue)
	Returns an iterator to the end of the `queue`.

pw_InlineVarLenEntryQueue_ConstIterator	pw_InlineVarLenEntryQueue_ConstEnd (pw_InlineVarLenEntryQueue_ConstHandle queue)

bool	pw_InlineVarLenEntryQueue_Empty (pw_InlineVarLenEntryQueue_ConstHandle queue)
	Returns true if the queue is empty, false if it has at least one entry.

uint32_t	pw_InlineVarLenEntryQueue_Size (pw_InlineVarLenEntryQueue_ConstHandle queue)

uint32_t	pw_InlineVarLenEntryQueue_MaxSize (pw_InlineVarLenEntryQueue_ConstHandle queue)

uint32_t	pw_InlineVarLenEntryQueue_SizeBytes (pw_InlineVarLenEntryQueue_ConstHandle queue)

uint32_t	pw_InlineVarLenEntryQueue_MaxSizeBytes (pw_InlineVarLenEntryQueue_ConstHandle 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)

void	pw_InlineVarLenEntryQueue_Clear (pw_InlineVarLenEntryQueue_Handle queue)
	Empties the queue.

uint32_t	pw_InlineVarLenEntryQueue_RawStorageSizeBytes (pw_InlineVarLenEntryQueue_ConstHandle queue)

void	pw_InlineVarLenEntryQueue_CopyEntries (pw_InlineVarLenEntryQueue_ConstHandle from, pw_InlineVarLenEntryQueue_Handle to)

void	pw_InlineVarLenEntryQueue_CopyEntriesOverwrite (pw_InlineVarLenEntryQueue_ConstHandle from, pw_InlineVarLenEntryQueue_Handle to)

void	pw_InlineVarLenEntryQueue_MoveEntries (pw_InlineVarLenEntryQueue_Handle from, pw_InlineVarLenEntryQueue_Handle to)

void	pw_InlineVarLenEntryQueue_MoveEntriesOverwrite (pw_InlineVarLenEntryQueue_Handle from, pw_InlineVarLenEntryQueue_Handle to)

Macro Definition Documentation

◆ PW_VARIABLE_LENGTH_ENTRY_QUEUE_DECLARE

#define PW_VARIABLE_LENGTH_ENTRY_QUEUE_DECLARE	(	variable,
		max_size_bytes
	)

Value:

  _PW_VAR_QUEUE_CHECK_SIZE(max_size_bytes)                               \
  uint32_t variable[_PW_VAR_QUEUE_SIZE_UINT32(max_size_bytes)] = {       \
      PW_VAR_QUEUE_DATA_SIZE_BYTES(max_size_bytes), /*head=*/0u, /*tail=*/0u}

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

See also pw_InlineVarLenEntryQueue_Init.

Parameters

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

Function Documentation

◆ pw_InlineVarLenEntryQueue_Begin()

pw_InlineVarLenEntryQueue_Iterator pw_InlineVarLenEntryQueue_Begin ( pw_InlineVarLenEntryQueue_Handle queue )

Returns an iterator to the start of the queue.

◆ pw_InlineVarLenEntryQueue_Clear()

void pw_InlineVarLenEntryQueue_Clear ( pw_InlineVarLenEntryQueue_Handle queue )

Empties the queue.

◆ pw_InlineVarLenEntryQueue_ConstBegin()

pw_InlineVarLenEntryQueue_ConstIterator pw_InlineVarLenEntryQueue_ConstBegin ( pw_InlineVarLenEntryQueue_ConstHandle queue )

◆ pw_InlineVarLenEntryQueue_ConstEnd()

pw_InlineVarLenEntryQueue_ConstIterator pw_InlineVarLenEntryQueue_ConstEnd ( pw_InlineVarLenEntryQueue_ConstHandle queue )

◆ pw_InlineVarLenEntryQueue_CopyEntries()

void pw_InlineVarLenEntryQueue_CopyEntries	(	pw_InlineVarLenEntryQueue_ConstHandle	from,
		pw_InlineVarLenEntryQueue_Handle	to
	)

Copies as many consecutive entries as will fit in the destination queue from a source queue to another, and returns the number of bytes copied.

◆ pw_InlineVarLenEntryQueue_CopyEntriesOverwrite()

void pw_InlineVarLenEntryQueue_CopyEntriesOverwrite	(	pw_InlineVarLenEntryQueue_ConstHandle	from,
		pw_InlineVarLenEntryQueue_Handle	to
	)

Copies consecutive entries from one queue to another, discarding entries from the destination queue as needed to make room. Some entries may not be copied if the data in the source queue is larger the destination queue's capacity. Returns the number of bytes copied.

◆ pw_InlineVarLenEntryQueue_Empty()

bool pw_InlineVarLenEntryQueue_Empty ( pw_InlineVarLenEntryQueue_ConstHandle queue )

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

◆ pw_InlineVarLenEntryQueue_End()

pw_InlineVarLenEntryQueue_Iterator pw_InlineVarLenEntryQueue_End ( pw_InlineVarLenEntryQueue_Handle queue )

Returns an iterator to the end of the queue.

◆ pw_InlineVarLenEntryQueue_Init()

void pw_InlineVarLenEntryQueue_Init	(	uint32_t	array[],
		size_t	array_size_uint32
	)

Initializes a BasicInlineVarLenEntryQueue in place within a uint32_t array. The array MUST be larger than PW_VARIABLE_LENGTH_ENTRY_QUEUE_HEADER_SIZE_UINT32 (3) elements.

◆ pw_InlineVarLenEntryQueue_MaxSize()

uint32_t pw_InlineVarLenEntryQueue_MaxSize ( pw_InlineVarLenEntryQueue_ConstHandle queue )

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

◆ pw_InlineVarLenEntryQueue_MaxSizeBytes()

uint32_t pw_InlineVarLenEntryQueue_MaxSizeBytes ( pw_InlineVarLenEntryQueue_ConstHandle queue )

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

void pw_InlineVarLenEntryQueue_MoveEntries	(	pw_InlineVarLenEntryQueue_Handle	from,
		pw_InlineVarLenEntryQueue_Handle	to
	)

Moves as many consecutive entries as will fit in the destination queue from a source queue to another, and returns the number of bytes moved.

◆ pw_InlineVarLenEntryQueue_MoveEntriesOverwrite()

void pw_InlineVarLenEntryQueue_MoveEntriesOverwrite	(	pw_InlineVarLenEntryQueue_Handle	from,
		pw_InlineVarLenEntryQueue_Handle	to
	)

Moves consecutive entries from one queue to another, discarding entries from the destination queue as needed to make room. Some entries may not be moved if the data in the source queue is larger the destination queue's capacity. Returns the number of bytes moved.

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

uint32_t pw_InlineVarLenEntryQueue_RawStorageSizeBytes ( pw_InlineVarLenEntryQueue_ConstHandle queue )

Underlying storage of the variable-length entry queue. May be used to memcpy the queue.

◆ pw_InlineVarLenEntryQueue_Size()

uint32_t pw_InlineVarLenEntryQueue_Size ( pw_InlineVarLenEntryQueue_ConstHandle queue )

Returns the number of variable-length entries in the queue. This is at most 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 at most 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().