inline_var_len_entry_queue.h File Reference

#include <cstddef>
#include <cstdint>
#include "pw_toolchain/constexpr_tag.h"
#include "pw_preprocessor/util.h"
#include "pw_varint/varint.h"
#include <limits>
#include <type_traits>
#include <utility>
#include "pw_containers/internal/raw_storage.h"
#include "pw_span/span.h"

Go to the source code of this file.

Classes
struct	pw_InlineVarLenEntryQueue_Iterator
struct	pw_InlineVarLenEntryQueue_Entry
class	pw::BasicInlineVarLenEntryQueue< T, kMaxSizeBytes >
class	pw::BasicInlineVarLenEntryQueue< T, containers::internal::kGenericSized >
class	pw::BasicInlineVarLenEntryQueue< T, kMaxSizeBytes >::Entry
	Refers to an entry in-place in the queue. Entries may be discontiguous. More...
class	pw::BasicInlineVarLenEntryQueue< T, kMaxSizeBytes >::Entry::iterator
class	pw::BasicInlineVarLenEntryQueue< T, kMaxSizeBytes >::iterator

Namespaces
namespace	pw
	Provides basic helpers for reading and writing UTF-8 encoded strings.

Macros
#define	PW_VARIABLE_LENGTH_ENTRY_QUEUE_DECLARE(variable, max_size_bytes)
#define	PW_VARIABLE_LENGTH_ENTRY_QUEUE_HEADER_SIZE_UINT32   (3)
#define	_PW_VAR_QUEUE_DATA_SIZE_UINT32(max_size_bytes)    ((_PW_VAR_QUEUE_DATA_SIZE_BYTES(max_size_bytes) + 3 /* round up */) / 4)
#define	_PW_VAR_QUEUE_DATA_SIZE_BYTES(max_size_bytes)
#define	_PW_VAR_QUEUE_ARRAY_SIZE_BYTES   queue[0]
#define	_PW_VAR_QUEUE_HEAD   queue[1]
#define	_PW_VAR_QUEUE_TAIL   queue[2]
#define	_PW_VAR_QUEUE_DATA   ((const uint8_t*)&queue[3])

Typedefs
typedef uint32_t *	pw_InlineVarLenEntryQueue_Handle
typedef const uint32_t *	pw_InlineVarLenEntryQueue_ConstHandle
template<size_t kMaxSizeBytes = containers::internal::kGenericSized>
using	pw::InlineVarLenEntryQueue = BasicInlineVarLenEntryQueue< std::byte, kMaxSizeBytes >
	Variable-length entry queue that uses std::byte for the byte type.

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)
static const uint8_t *	_pw_InlineVarLenEntryQueue_Entry_GetPointer (const pw_InlineVarLenEntryQueue_Entry *entry, size_t index)
const uint8_t *	_pw_InlineVarLenEntryQueue_Entry_GetPointerChecked (const pw_InlineVarLenEntryQueue_Entry *entry, size_t index)

Detailed Description

A InlineVarLenEntryQueue is a queue of inline variable-length binary entries. It is implemented as a ring (circular) buffer and supports operations to append entries and overwrite if necessary. Entries may be zero bytes up to the maximum size supported by the queue.

The InlineVarLenEntryQueue has a few interesting properties.

• Data and metadata are stored inline in a contiguous block of uint32_t-aligned memory.
• The data structure is trivially copyable.
• All state changes are accomplished with a single update to a uint32_t. The memory is always in a valid state and may be parsed offline.

This data structure is a much simpler version of

embed:rst:inline :cpp:class:`pw::ring_buffer::PrefixedEntryRingBuffer` 

. Prefer this sized-entry ring buffer to PrefixedEntryRingBuffer when:

• A simple ring buffer of variable-length entries is needed. Advanced features like multiple readers and a user-defined preamble are not required.
• A consistent, parsable, in-memory representation is required (e.g. to decode the buffer from a block of memory).
• C support is required.

InlineVarLenEntryQueue is implemented in C and provides complete C and C++ APIs. The InlineVarLenEntryQueue C++ class is structured similarly to pw::InlineQueue and pw::Vector.

Macro Definition Documentation

_PW_VAR_QUEUE_DATA_SIZE_BYTES

#define _PW_VAR_QUEUE_DATA_SIZE_BYTES

(

max_size_bytes

)

Value:

  (PW_VARINT_ENCODED_SIZE_BYTES(max_size_bytes) + max_size_bytes + \
   1 /*end byte*/)