Skip to content

Commit

Permalink
pw_containers: Rename VariableLengthEntryQueue
Browse files Browse the repository at this point in the history 
Rename VariableLengthEntryQueue to InlineVarLenEntryQueue. "Inline" is
important for describing the data structure and is necessary for
consistency with other Pigweed containers.

Change-Id: I171885a4944bade1468e72093c99cf4aef7cb651
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/187311
Pigweed-Auto-Submit: Wyatt Hepler <[email protected]>
Reviewed-by: Armando Montanez <[email protected]>
Commit-Queue: Auto-Submit <[email protected]>
  • Loading branch information
@255
255 authored and CQ Bot Account committed Feb 26, 2024
1 parent 17c5867 commit 55dcce2
Show file tree
Hide file tree
Showing 6 changed files with 295 additions and 304 deletions.
44 changes: 22 additions & 22 deletions pw_containers/docs.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@ pw::InlineQueue
---------------
.. doxygentypedef:: pw::InlineQueue

----------------------------
pw::VariableLengthEntryQueue
----------------------------
--------------------------
pw::InlineVarLenEntryQueue
--------------------------
.. doxygenfile:: pw_containers/inline_var_len_entry_queue.h
:sections: detaileddescription

Expand All @@ -49,14 +49,14 @@ Example
:sync: c++

Queues are declared with their max size
(``VariableLengthEntryQueue<kMaxSize>``) but may be used without
specifying the size (``VariableLengthEntryQueue<>&``).
(``InlineVarLenEntryQueue<kMaxSize>``) but may be used without
specifying the size (``InlineVarLenEntryQueue<>&``).

.. code-block:: c++

// Declare a queue with capacity sufficient for one 10-byte entry or
// multiple smaller entries.
pw::VariableLengthEntryQueue<10> queue;
pw::InlineVarLenEntryQueue<10> queue;

// Push an entry, asserting if the entry does not fit.
queue.push(queue, data)
Expand All @@ -68,14 +68,14 @@ Example
// Remove an entry.
queue.pop();

Alternately, a ``VariableLengthEntryQueue`` may be initialized in an
Alternately, a ``InlineVarLenEntryQueue`` may be initialized in an
existing ``uint32_t`` array.

.. code-block:: c++

// Initialize a VariableLengthEntryQueue.
// Initialize a InlineVarLenEntryQueue.
uint32_t buffer[32];
auto& queue = pw::VariableLengthEntryQueue<>::Init(buffer);
auto& queue = pw::InlineVarLenEntryQueue<>::Init(buffer);

// Largest supported entry is 114 B (13 B overhead + 1 B prefix)
assert(queue.max_size_bytes() == 114u);
Expand All @@ -86,8 +86,8 @@ Example
.. tab-item:: C
:sync: c

A ``VariableLengthEntryQueue`` may be declared and initialized in C with
the :c:macro:`PW_VARIABLE_LENGTH_ENTRY_QUEUE_DECLARE` macro.
A ``InlineVarLenEntryQueue`` may be declared and initialized in C with the
:c:macro:`PW_VARIABLE_LENGTH_ENTRY_QUEUE_DECLARE` macro.

.. code-block:: c
Expand All @@ -96,39 +96,39 @@ Example
PW_VARIABLE_LENGTH_ENTRY_QUEUE_DECLARE(queue, 10);
// Push an entry, asserting if the entry does not fit.
pw_VariableLengthEntryQueue_Push(queue, "12345", 5);
pw_InlineVarLenEntryQueue_Push(queue, "12345", 5);
// Use push_overwrite() to push entries, overwriting older entries
// as needed.
pw_VariableLengthEntryQueue_PushOverwrite(queue, "abcdefg", 7);
pw_InlineVarLenEntryQueue_PushOverwrite(queue, "abcdefg", 7);
// Remove an entry.
pw_VariableLengthEntryQueue_Pop(queue);
pw_InlineVarLenEntryQueue_Pop(queue);
Alternately, a ``VariableLengthEntryQueue`` may be initialized in an
Alternately, a ``InlineVarLenEntryQueue`` may be initialized in an
existing ``uint32_t`` array.

.. code-block:: c
// Initialize a VariableLengthEntryQueue.
// Initialize a InlineVarLenEntryQueue.
uint32_t buffer[32];
pw_VariableLengthEntryQueue_Init(buffer, 32);
pw_InlineVarLenEntryQueue_Init(buffer, 32);
// Largest supported entry is 114 B (13 B overhead + 1 B prefix)
assert(pw_VariableLengthEntryQueue_MaxSizeBytes(buffer) == 114u);
assert(pw_InlineVarLenEntryQueue_MaxSizeBytes(buffer) == 114u);
// Write some data
pw_VariableLengthEntryQueue_PushOverwrite(buffer, "123", 3);
pw_InlineVarLenEntryQueue_PushOverwrite(buffer, "123", 3);
Queue vs. deque
===============
This module provides :cpp:type:`VariableLengthEntryQueue`, but no corresponding
``VariableLengthEntryDeque`` class. Following the C++ Standard Library style,
This module provides :cpp:type:`InlineVarLenEntryQueue`, but no corresponding
``InlineVarLenEntryDeque`` class. Following the C++ Standard Library style,
the deque class would provide ``push_front()`` and ``pop_back()`` operations in
addition to ``push_back()`` and ``pop_front()`` (equivalent to a queue's
``push()`` and ``pop()``).

There is no ``VariableLengthEntryDeque`` class because there is no efficient way
There is no ``InlineVarLenEntryDeque`` class because there is no efficient way
to implement ``push_front()`` and ``pop_back()``. These operations would
necessarily be O(n), since each entry knows the position of the next entry, but
not the previous, as in a single-linked list. Given that these operations would
Expand Down
64 changes: 31 additions & 33 deletions pw_containers/inline_var_len_entry_queue.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ static const uint8_t* Data(const uint32_t* queue) {
return (const uint8_t*)&queue[3];
}

static uint32_t WrapIndex(pw_VariableLengthEntryQueue_ConstHandle queue,
static uint32_t WrapIndex(pw_InlineVarLenEntryQueue_ConstHandle queue,
uint32_t offset) {
if (offset >= BufferSize(queue)) {
offset -= BufferSize(queue);
Expand All @@ -49,7 +49,7 @@ typedef struct {
} EntrySize;

// Returns the size of an entry, including both the prefix length and data size.
static EntrySize ReadEntrySize(pw_VariableLengthEntryQueue_ConstHandle queue,
static EntrySize ReadEntrySize(pw_InlineVarLenEntryQueue_ConstHandle queue,
uint32_t offset) {
EntrySize size = {0, 0};

Expand All @@ -65,7 +65,7 @@ static EntrySize ReadEntrySize(pw_VariableLengthEntryQueue_ConstHandle queue,
return size;
}

static uint32_t EncodePrefix(pw_VariableLengthEntryQueue_ConstHandle queue,
static uint32_t EncodePrefix(pw_InlineVarLenEntryQueue_ConstHandle queue,
uint8_t prefix[PW_VARINT_MAX_INT32_SIZE_BYTES],
uint32_t data_size_bytes) {
const uint32_t prefix_size = (uint32_t)pw_varint_Encode32(
Expand All @@ -74,25 +74,25 @@ static uint32_t EncodePrefix(pw_VariableLengthEntryQueue_ConstHandle queue,
// Check that the ring buffer is capable of holding entries of this size.
PW_CHECK_UINT_LE(prefix_size + data_size_bytes,
Capacity(queue),
"Entry is too large for this VariableLengthEntryQueue");
"Entry is too large for this InlineVarLenEntryQueue");
return prefix_size;
}

// Returns the total encoded size of an entry.
static uint32_t ReadEncodedEntrySize(
pw_VariableLengthEntryQueue_ConstHandle queue, uint32_t offset) {
pw_InlineVarLenEntryQueue_ConstHandle queue, uint32_t offset) {
const EntrySize entry_size = ReadEntrySize(queue, offset);
return entry_size.prefix + entry_size.data;
}

static uint32_t PopNonEmpty(pw_VariableLengthEntryQueue_Handle queue) {
static uint32_t PopNonEmpty(pw_InlineVarLenEntryQueue_Handle queue) {
const uint32_t entry_size = ReadEncodedEntrySize(queue, HEAD(queue));
HEAD(queue) = WrapIndex(queue, HEAD(queue) + entry_size);
return entry_size;
}

// Copies data to the buffer, wrapping around the end if needed.
static uint32_t CopyAndWrap(pw_VariableLengthEntryQueue_Handle queue,
static uint32_t CopyAndWrap(pw_InlineVarLenEntryQueue_Handle queue,
uint32_t tail,
const uint8_t* data,
uint32_t size) {
Expand All @@ -111,7 +111,7 @@ static uint32_t CopyAndWrap(pw_VariableLengthEntryQueue_Handle queue,
return WrapIndex(queue, tail + size);
}

static void AppendEntryKnownToFit(pw_VariableLengthEntryQueue_Handle queue,
static void AppendEntryKnownToFit(pw_InlineVarLenEntryQueue_Handle queue,
const uint8_t* prefix,
uint32_t prefix_size,
const void* data,
Expand All @@ -123,17 +123,17 @@ static void AppendEntryKnownToFit(pw_VariableLengthEntryQueue_Handle queue,
}

static inline uint32_t AvailableBytes(
pw_VariableLengthEntryQueue_ConstHandle queue) {
pw_InlineVarLenEntryQueue_ConstHandle queue) {
uint32_t tail = TAIL(queue);
if (tail < HEAD(queue)) {
tail += BufferSize(queue);
}
return Capacity(queue) - (tail - HEAD(queue));
}

void pw_VariableLengthEntryQueue_Push(pw_VariableLengthEntryQueue_Handle queue,
const void* data,
const uint32_t data_size_bytes) {
void pw_InlineVarLenEntryQueue_Push(pw_InlineVarLenEntryQueue_Handle queue,
const void* data,
const uint32_t data_size_bytes) {
uint8_t prefix[PW_VARINT_MAX_INT32_SIZE_BYTES];
uint32_t prefix_size = EncodePrefix(queue, prefix, data_size_bytes);

Expand All @@ -143,8 +143,8 @@ void pw_VariableLengthEntryQueue_Push(pw_VariableLengthEntryQueue_Handle queue,
AppendEntryKnownToFit(queue, prefix, prefix_size, data, data_size_bytes);
}

void pw_VariableLengthEntryQueue_PushOverwrite(
pw_VariableLengthEntryQueue_Handle queue,
void pw_InlineVarLenEntryQueue_PushOverwrite(
pw_InlineVarLenEntryQueue_Handle queue,
const void* data,
const uint32_t data_size_bytes) {
uint8_t prefix[PW_VARINT_MAX_INT32_SIZE_BYTES];
Expand All @@ -158,24 +158,24 @@ void pw_VariableLengthEntryQueue_PushOverwrite(
AppendEntryKnownToFit(queue, prefix, prefix_size, data, data_size_bytes);
}

void pw_VariableLengthEntryQueue_Pop(pw_VariableLengthEntryQueue_Handle queue) {
PW_CHECK(!pw_VariableLengthEntryQueue_Empty(queue));
void pw_InlineVarLenEntryQueue_Pop(pw_InlineVarLenEntryQueue_Handle queue) {
PW_CHECK(!pw_InlineVarLenEntryQueue_Empty(queue));
PopNonEmpty(queue);
}

void pw_VariableLengthEntryQueue_Iterator_Advance(
pw_VariableLengthEntryQueue_Iterator* iterator) {
void pw_InlineVarLenEntryQueue_Iterator_Advance(
pw_InlineVarLenEntryQueue_Iterator* iterator) {
iterator->_pw_offset = WrapIndex(
iterator->_pw_queue,
iterator->_pw_offset +
ReadEncodedEntrySize(iterator->_pw_queue, iterator->_pw_offset));
}

pw_VariableLengthEntryQueue_Entry pw_VariableLengthEntryQueue_GetEntry(
const pw_VariableLengthEntryQueue_Iterator* iterator) {
pw_VariableLengthEntryQueue_ConstHandle queue = iterator->_pw_queue;
pw_InlineVarLenEntryQueue_Entry pw_InlineVarLenEntryQueue_GetEntry(
const pw_InlineVarLenEntryQueue_Iterator* iterator) {
pw_InlineVarLenEntryQueue_ConstHandle queue = iterator->_pw_queue;

pw_VariableLengthEntryQueue_Entry entry;
pw_InlineVarLenEntryQueue_Entry entry;
EntrySize size = ReadEntrySize(queue, iterator->_pw_offset);
uint32_t offset_1 = WrapIndex(queue, iterator->_pw_offset + size.prefix);

Expand All @@ -194,10 +194,8 @@ pw_VariableLengthEntryQueue_Entry pw_VariableLengthEntryQueue_GetEntry(
return entry;
}

uint32_t pw_VariableLengthEntryQueue_Entry_Copy(
const pw_VariableLengthEntryQueue_Entry* entry,
void* dest,
uint32_t count) {
uint32_t pw_InlineVarLenEntryQueue_Entry_Copy(
const pw_InlineVarLenEntryQueue_Entry* entry, void* dest, uint32_t count) {
PW_DCHECK(dest != NULL || count == 0u);

const uint32_t entry_size = entry->size_1 + entry->size_2;
Expand All @@ -217,14 +215,14 @@ uint32_t pw_VariableLengthEntryQueue_Entry_Copy(
return to_copy;
}

const uint8_t* _pw_VariableLengthEntryQueue_Entry_GetPointerChecked(
const pw_VariableLengthEntryQueue_Entry* entry, size_t index) {
const uint8_t* _pw_InlineVarLenEntryQueue_Entry_GetPointerChecked(
const pw_InlineVarLenEntryQueue_Entry* entry, size_t index) {
PW_CHECK_UINT_LT(index, entry->size_1 + entry->size_2);
return _pw_VariableLengthEntryQueue_Entry_GetPointer(entry, index);
return _pw_InlineVarLenEntryQueue_Entry_GetPointer(entry, index);
}

uint32_t pw_VariableLengthEntryQueue_Size(
pw_VariableLengthEntryQueue_ConstHandle queue) {
uint32_t pw_InlineVarLenEntryQueue_Size(
pw_InlineVarLenEntryQueue_ConstHandle queue) {
uint32_t entry_count = 0;
uint32_t offset = HEAD(queue);

Expand All @@ -235,8 +233,8 @@ uint32_t pw_VariableLengthEntryQueue_Size(
return entry_count;
}

uint32_t pw_VariableLengthEntryQueue_SizeBytes(
pw_VariableLengthEntryQueue_ConstHandle queue) {
uint32_t pw_InlineVarLenEntryQueue_SizeBytes(
pw_InlineVarLenEntryQueue_ConstHandle queue) {
uint32_t total_entry_size_bytes = 0;
uint32_t offset = HEAD(queue);

Expand Down
Loading

0 comments on commit 55dcce2

Please sign in to comment.