pw::multibuf::v2::internal::Entry Struct Reference

Overview

Describes either a memory location or a view of an associated location.

This module stores byte buffers in queues using sequences of entries. The first entry holds an address, and subsequent entries hold the offset and lengths of ever-narrower views of that data. This provides a compact representation of data encoded using nested or layered protocols.

For example, in a TCP/IP stack:

• The first entry hold addresses to Ethernet frames.
• The second entry holds a zero offset and the whole frame length.
• The third entry holds the offset and length describing the IP data.
• The fourth entry holds the offset and length describing the TCP data.

Classes
struct	BaseView
	Describes the entire memory region. More...
struct	View

Public Types
using	Deque = DynamicDeque< Entry >
using	size_type = Deque::size_type
using	difference_type = Deque::difference_type

Static Public Member Functions
static constexpr size_type	num_chunks (const Deque &deque, size_type entries_per_chunk)
	Returns the number of chunks in a deque.
static constexpr size_type	num_layers (size_type entries_per_chunk)
static constexpr size_type	memory_context_index (size_type chunk, size_type entries_per_chunk)
	Returns the index to the data entry of a given chunk.
static constexpr size_type	data_index (size_type chunk, size_type entries_per_chunk)
	Returns the index to the data entry of a given chunk.
static constexpr size_type	base_view_index (size_type chunk, size_type entries_per_chunk)
	Returns the index to the base view entry of a given chunk.
static constexpr size_type	view_index (size_type chunk, size_type entries_per_chunk, size_type layer)
	Returns the index to a view entry of a given chunk.
static constexpr size_type	top_view_index (size_type chunk, size_type entries_per_chunk)
	Returns the index to the top view entry of a given chunk.
static constexpr std::byte *	GetData (const Deque &deque, size_type chunk, size_type entries_per_chunk)
	Returns the memory backing the chunk at the given index.
static constexpr bool	IsOwned (const Deque &deque, size_type chunk, size_type entries_per_chunk)
static constexpr bool	IsShared (const Deque &deque, size_type chunk, size_type entries_per_chunk)
static constexpr bool	IsSealed (const Deque &deque, size_type chunk, size_type entries_per_chunk)
	Returns whether the chunk is part of a sealed layer.
static constexpr Deallocator &	GetDeallocator (const Deque &deque, size_type chunk, size_type entries_per_chunk)
	Returns the deallocator for a chunk, which must be owned.
static constexpr allocator::internal::ControlBlock &	GetControlBlock (const Deque &deque, size_type chunk, size_type entries_per_chunk)
	Returns the control block for a chunk, which must be shared.
static constexpr bool	IsBoundary (const Deque &deque, size_type chunk, size_type entries_per_chunk, size_type layer)
	Returns whether the given layer of a chunk represents a fragment boundary.
static constexpr bool	IsBoundary (const Deque &deque, size_type chunk, size_type entries_per_chunk)
	Returns whether the top layer of a chunk represents a fragment boundary.
static constexpr size_type	GetOffset (const Deque &deque, size_type chunk, size_type entries_per_chunk, size_type layer)
	Returns the offset of the given layer of the chunk.
static constexpr size_type	GetOffset (const Deque &deque, size_type chunk, size_type entries_per_chunk)
	Returns the offset of the top layer of the chunk.
static constexpr size_type	GetRelativeOffset (const Deque &deque, size_type chunk, size_type entries_per_chunk, size_type layer)
static constexpr size_type	GetRelativeOffset (const Deque &deque, size_type chunk, size_type entries_per_chunk)
static constexpr size_type	GetLength (const Deque &deque, size_type chunk, size_type entries_per_chunk, size_type layer)
	Returns the length of the given layer of the chunk.
static constexpr size_type	GetLength (const Deque &deque, size_type chunk, size_type entries_per_chunk)
	Returns the length of the top layer of the chunk.
static constexpr ByteSpan	GetView (const Deque &deque, size_type chunk, size_type entries_per_chunk, size_type layer)
	Returns a view of the visible data length of the chunk at the given layer.
static constexpr ByteSpan	GetView (const Deque &deque, size_type chunk, size_type entries_per_chunk)
	Returns a view of the visible data length of the chunk at the top layer.

Public Attributes
union {
Deallocator *   deallocator
	Optional deallocator involved in freeing owned memory.
allocator::internal::ControlBlock *   control_block
	Optional control block involved in freeing shared memory.
std::byte *   data
	Pointer to memory.
BaseView   base_view
View   view
};

Static Public Attributes
static constexpr size_t	kMaxSize = ~(1U << 15)
	Offset and length must fit in 15 bits.
static constexpr size_type	kMemoryContextIndex = 0
	Per-chunk index entry that holds the deallocator or control block.
static constexpr size_type	kDataIndex = 1
	Per-chunk index entry that holds the data pointer.
static constexpr size_type	kBaseViewIndex = 2
	Per-chunk index entry that holds the base view of the data.
static constexpr size_type	kMinEntriesPerChunk = 3
	Minimum number of entries per chunk.

Member Function Documentation

GetRelativeOffset() [1/2]

static constexpr size_type pw::multibuf::v2::internal::Entry::GetRelativeOffset ( const Deque &  deque, size_type  chunk, size_type  entries_per_chunk  )

inlinestaticconstexpr

Returns the offset of the top layer of the chunk relative to the layer below it.

GetRelativeOffset() [2/2]

static constexpr size_type pw::multibuf::v2::internal::Entry::GetRelativeOffset ( const Deque &  deque, size_type  chunk, size_type  entries_per_chunk, size_type  layer  )

inlinestaticconstexpr

Returns the offset of the given layer of the chunk relative to the layer below it.

IsOwned()

static constexpr bool pw::multibuf::v2::internal::Entry::IsOwned ( const Deque &  deque, size_type  chunk, size_type  entries_per_chunk  )

inlinestaticconstexpr

Returns whether the memory backing the chunk at the given index is owned by this object.

IsShared()

static constexpr bool pw::multibuf::v2::internal::Entry::IsShared ( const Deque &  deque, size_type  chunk, size_type  entries_per_chunk  )

inlinestaticconstexpr

Returns whether the memory backing the chunk at the given index is shared with other objects.

num_layers()

static constexpr size_type pw::multibuf::v2::internal::Entry::num_layers ( size_type  entries_per_chunk )

inlinestaticconstexpr

Returns the number of layers in a chunk given the number of entries used per chunk.

Member Data Documentation

union { ... } pw::multibuf::v2::internal::Entry::@7

Contents of the entry.

Entries fit in a single word on 32-bit platforms and larger. Fields are ordered in such a way to ensure this is true on supported platforms.

The index of the entry in the deque modulo the number of entries per chunk determines what information is stored in the entry. For example, if the index is congruent to kDataIndex, a pointer to bytes is stored.

As a special case, the information stored in entries with indices congruent to kMemoryContextIndex also depends on the corresponding entries congruent to kBaseViewIndex. If the latter has the owned flag set, a pointer to a deallocator is stored. If it has the shared flag set, a pointer to a control block is stored.

---

The documentation for this struct was generated from the following file:

• pw_multibuf/v2/public/pw_multibuf/v2/internal/entry.h