Overview

A byte buffer optimized for zero-copy data transfer that mimics v1::MultiBuf.

This function can be used as a drop-in replacement for v1::MultiBuf while migrating to using pw_multibuf/v2.

Internally, this object wraps a v2::MultiBuf and exposes a portion of its API. In particular, it exposes the TryReserveChunks() method, which fallibly allocates space for chunks. Infallible v1 methods like PushBackChunk() will assert on allocation failure.

As a result, once a component has switched to using this type, it is strongly recommended to follow up by refactoring to provide an allocator to v1_adapter::MultiBuf at construction and reserving memory for chunks before inserting them.

Public Types
using	size_type = v2::MultiBuf::size_type

using	difference_type = v2::MultiBuf::difference_type

using	iterator = v2::MultiBuf::iterator

using	const_iterator = v2::MultiBuf::const_iterator

using	pointer = v2::MultiBuf::pointer

using	const_pointer = v2::MultiBuf::const_pointer

using	reference = v2::MultiBuf::reference

using	const_reference = v2::MultiBuf::const_reference

using	value_type = v2::MultiBuf::value_type

Public Member Functions
	MultiBuf (const MultiBuf &other)=delete

MultiBuf &	operator= (const MultiBuf &other)=delete

	MultiBuf (MultiBuf &&other) noexcept=default

MultiBuf &	operator= (MultiBuf &&other) noexcept=default

constexpr v2::TrackedMultiBuf *	v2 ()

constexpr const v2::TrackedMultiBuf *	v2 () const

void	Release () noexcept

constexpr size_t	size () const

constexpr bool	empty () const

bool	IsContiguous () const

std::optional< ByteSpan >	ContiguousSpan ()

std::optional< ConstByteSpan >	ContiguousSpan () const

constexpr iterator	begin ()
	Returns an iterator pointing to the first byte of this `MultiBuf`.

constexpr const_iterator	begin () const

constexpr const_iterator	cbegin () const

constexpr iterator	end ()
	Returns an iterator pointing to the end of this `MultiBuf`.

constexpr const_iterator	end () const

constexpr const_iterator	cend () const

bool	ClaimPrefix (size_t bytes_to_claim)

bool	ClaimSuffix (size_t bytes_to_claim)

void	DiscardPrefix (size_t bytes_to_discard)

void	Slice (size_t begin, size_t end)

void	Truncate (size_t len)

void	TruncateAfter (iterator pos)

std::optional< MultiBuf >	TakePrefix (size_t bytes_to_take)

std::optional< MultiBuf >	TakeSuffix (size_t bytes_to_take)

void	PushPrefix (MultiBuf &&front)

void	PushSuffix (MultiBuf &&tail)

StatusWithSize	CopyTo (ByteSpan dest, size_t position=0) const

StatusWithSize	CopyFrom (ConstByteSpan source, size_t position=0)

StatusWithSize	CopyFromAndTruncate (ConstByteSpan source, size_t position=0)

void	PushFrontChunk (OwnedChunk &&chunk)

void	PushBackChunk (OwnedChunk &&chunk)

OwnedChunk	TakeFrontChunk ()

MultiBufChunks::iterator	InsertChunk (MultiBufChunks::iterator position, OwnedChunk &&chunk)

std::tuple< MultiBufChunks::iterator, OwnedChunk >	TakeChunk (MultiBufChunks::iterator position)

constexpr MultiBufChunks	Chunks ()
	Returns a `Chunk`-oriented view of this `MultiBuf`.

constexpr const MultiBufChunks	Chunks () const

constexpr const MultiBufChunks	ConstChunks () const
	Returns a `const Chunk`-oriented view of this `MultiBuf`.

constexpr	MultiBuf (Allocator &allocator)

template<v2::Property... kProperties>
constexpr	MultiBuf (v2::BasicMultiBuf< kProperties... > &&mb)

template<v2::Property... kProperties>
constexpr MultiBuf &	operator= (v2::BasicMultiBuf< kProperties... > &&mb)

template<typename MultiBufType >
constexpr	MultiBuf (v2::internal::Instance< MultiBufType > &&mbi)

template<typename MultiBufType >
constexpr MultiBuf &	operator= (v2::internal::Instance< MultiBufType > &&mbi)

constexpr v2::TrackedMultiBuf *	operator-> ()

constexpr const v2::TrackedMultiBuf *	operator-> () const

constexpr v2::TrackedMultiBuf &	operator* () &

constexpr const v2::TrackedMultiBuf &	operator* () const &

constexpr v2::TrackedMultiBuf &&	operator* () &&

constexpr const v2::TrackedMultiBuf &&	operator* () const &&

template<typename MultiBufType >
constexpr	operator MultiBufType & () &

template<typename MultiBufType >
constexpr	operator const MultiBufType & () const &

template<typename MultiBufType >
constexpr	operator MultiBufType && () &&

template<typename MultiBufType >
constexpr	operator const MultiBufType && () const &&

Static Public Member Functions
static MultiBuf	FromChunk (OwnedChunk &&chunk)

Member Function Documentation

◆ begin()

constexpr iterator pw::multibuf::v1_adapter::MultiBuf::begin ( )

inlineconstexpr

Returns an iterator pointing to the first byte of this MultiBuf.

◆ Chunks()

constexpr MultiBufChunks pw::multibuf::v1_adapter::MultiBuf::Chunks ( )

inlineconstexpr

Returns a Chunk-oriented view of this MultiBuf.

◆ ClaimPrefix()

bool pw::multibuf::v1_adapter::MultiBuf::ClaimPrefix ( size_t bytes_to_claim )

Attempts to add bytes_to_claim to the front of this buffer by advancing its range backwards in memory. Returns true if the operation succeeded.

This will only succeed if the first Chunk in this buffer points to a section of a region that has unreferenced bytes preceding it. See also Chunk::ClaimPrefix.

This method will acquire a mutex and is not IRQ safe.

◆ ClaimSuffix()

bool pw::multibuf::v1_adapter::MultiBuf::ClaimSuffix ( size_t bytes_to_claim )

Attempts to add bytes_to_claim to the front of this buffer by advancing its range forwards in memory. Returns true if the operation succeeded.

This will only succeed if the last Chunk in this buffer points to a section of a region that has unreferenced bytes following it. See also Chunk::ClaimSuffix.

This method will acquire a mutex and is not IRQ safe.

◆ ConstChunks()

constexpr const MultiBufChunks pw::multibuf::v1_adapter::MultiBuf::ConstChunks ( ) const

inlineconstexpr

Returns a const Chunk-oriented view of this MultiBuf.

◆ ContiguousSpan()

std::optional< ByteSpan > pw::multibuf::v1_adapter::MultiBuf::ContiguousSpan ( )

If the MultiBuf is contiguous, returns it as a span. The span will be empty if the MultiBuf is empty.

A MultiBuf is contiguous if it is comprised of either:

one non-empty chunk,
only empty chunks, or
no chunks at all.

◆ CopyFrom()

StatusWithSize pw::multibuf::v1_adapter::MultiBuf::CopyFrom	(	ConstByteSpan	source,
		size_t	position = `0`
	)

Copies bytes from the provided buffer into the multibuf.

Parameters

[in]	source	Data to copy into the `MultiBuf`.
[in]	position	Offset in the `MultiBuf` from which to start.

Returns

OK: All bytes were copied. The pw::StatusWithSize includes the number of bytes copied, which is the size of the MultiBuf.
RESOURCE_EXHAUSTED: Some bytes were copied, but the source was larger than the destination. The pw::StatusWithSize includes the number of bytes copied.

◆ CopyFromAndTruncate()

StatusWithSize pw::multibuf::v1_adapter::MultiBuf::CopyFromAndTruncate	(	ConstByteSpan	source,
		size_t	position = `0`
	)

Copies bytes from the provided buffer into this MultiBuf and truncates it to the end of the copied data. This is a more efficient version of:

if (multibuf.CopyFrom(destination).ok()) {
  multibuf.Truncate(destination.size());
}

Parameters

[in]	source	Data to copy into the `MultiBuf`.
[in]	position	Offset in the `MultiBuf` from which to start.

Returns

OK: All bytes were copied and the MultiBuf was truncated. The pw::StatusWithSize includes the new MultiBuf::size.
RESOURCE_EXHAUSTED: Some bytes were copied, but the source buffer was larger than the MultiBuf. The returned pw::StatusWithSize includes the number of bytes copied, which is the size of the MultiBuf.

◆ CopyTo()

StatusWithSize pw::multibuf::v1_adapter::MultiBuf::CopyTo	(	ByteSpan	dest,
		size_t	position = `0`
	)		const

Copies bytes from the multibuf into the provided buffer.

Parameters

[out]	dest	Destination into which to copy data from the `MultiBuf`.
[in]	position	Offset in the `MultiBuf` from which to start.

Returns

OK: All bytes were copied into the destination. The pw::StatusWithSize includes the number of bytes copied, which is the size of the MultiBuf.
RESOURCE_EXHAUSTED: Some bytes were copied, but the MultiBuf was larger than the destination buffer. The pw::StatusWithSize includes the number of bytes copied.

◆ DiscardPrefix()

void pw::multibuf::v1_adapter::MultiBuf::DiscardPrefix ( size_t bytes_to_discard )

Shrinks this handle to refer to the data beginning at offset bytes_to_discard.

Does not modify the underlying data. The discarded memory continues to be held by the underlying region as long as any Chunks exist within it. This allows the memory to be later reclaimed using ClaimPrefix.

This method will acquire a mutex and is not IRQ safe.

◆ empty()

constexpr bool pw::multibuf::v1_adapter::MultiBuf::empty ( ) const

inlineconstexpr

Returns whether the MultiBuf contains any bytes (size() == 0).

This method's complexity is O(Chunks().size()), but will be more efficient than size() == 0 in most cases.

◆ end()

constexpr iterator pw::multibuf::v1_adapter::MultiBuf::end ( )

inlineconstexpr

Returns an iterator pointing to the end of this MultiBuf.

◆ FromChunk()

static MultiBuf pw::multibuf::v1_adapter::MultiBuf::FromChunk ( OwnedChunk && chunk )

static

◆ InsertChunk()

MultiBufChunks::iterator pw::multibuf::v1_adapter::MultiBuf::InsertChunk	(	MultiBufChunks::iterator	position,
		OwnedChunk &&	chunk
	)

◆ IsContiguous()

bool pw::multibuf::v1_adapter::MultiBuf::IsContiguous ( ) const

inline

Returns if the MultiBuf is contiguous. A MultiBuf is contiguous if it is comprised of either:

one non-empty chunk,
only empty chunks, or
no chunks at all.

◆ PushBackChunk()

void pw::multibuf::v1_adapter::MultiBuf::PushBackChunk ( OwnedChunk && chunk )

◆ PushFrontChunk()

void pw::multibuf::v1_adapter::MultiBuf::PushFrontChunk ( OwnedChunk && chunk )

◆ PushPrefix()

void pw::multibuf::v1_adapter::MultiBuf::PushPrefix ( MultiBuf && front )

Pushes front onto the front of this MultiBuf.

This operation does not move any data and is O(front.Chunks().size()).

◆ PushSuffix()

void pw::multibuf::v1_adapter::MultiBuf::PushSuffix ( MultiBuf && tail )

Pushes tail onto the end of this MultiBuf.

This operation does not move any data and is O(Chunks().size()).

◆ Release()

void pw::multibuf::v1_adapter::MultiBuf::Release ( )

noexcept

Decrements the reference count on the underlying chunks of data and empties this MultiBuf so that size() == 0.

Does not modify the underlying data, but may cause it to be deallocated.

This method is equivalent to { MultiBuf _unused = std::move(multibuf); }

This method will acquire a mutex and is not IRQ safe.

◆ size()

constexpr size_t pw::multibuf::v1_adapter::MultiBuf::size ( ) const

inlineconstexpr

Returns the number of bytes in this container.

This method's complexity is O(Chunks().size()).

◆ Slice()

void pw::multibuf::v1_adapter::MultiBuf::Slice	(	size_t	begin,
		size_t	end
	)

Shrinks this handle to refer to data in the range begin..<end.

Does not modify the underlying data. The discarded memory continues to be held by the underlying region as long as any Chunks exist within it. This allows the memory to be later reclaimed using ClaimPrefix or ClaimSuffix.

This method will acquire a mutex and is not IRQ safe.

◆ TakeChunk()

std::tuple< MultiBufChunks::iterator, OwnedChunk > pw::multibuf::v1_adapter::MultiBuf::TakeChunk ( MultiBufChunks::iterator position )

◆ TakeFrontChunk()

OwnedChunk pw::multibuf::v1_adapter::MultiBuf::TakeFrontChunk ( )

inline

◆ TakePrefix()

std::optional< MultiBuf > pw::multibuf::v1_adapter::MultiBuf::TakePrefix ( size_t bytes_to_take )

Attempts to shrink this handle to refer to the data beginning at offset bytes_to_take, returning the first bytes_to_take bytes as a new MultiBuf.

If the inner call to AllocateChunkClass fails, this function will return std::nullopt and this handle's span will not change.

This method will acquire a mutex and is not IRQ safe.

◆ TakeSuffix()

std::optional< MultiBuf > pw::multibuf::v1_adapter::MultiBuf::TakeSuffix ( size_t bytes_to_take )

Attempts to shrink this handle to refer only the first len - bytes_to_take bytes, returning the last bytes_to_take bytes as a new MultiBuf.

If the inner call to AllocateChunkClass fails, this function will return std::nullopt and this handle's span will not change.

This method will acquire a mutex and is not IRQ safe.

◆ Truncate()

void pw::multibuf::v1_adapter::MultiBuf::Truncate ( size_t len )

Shrinks this handle to refer to only the first len bytes.

Does not modify the underlying data. The discarded memory continues to be held by the underlying region as long as any Chunks exist within it. This allows the memory to be later reclaimed using ClaimSuffix.

This method will acquire a mutex and is not IRQ safe.

◆ TruncateAfter()

void pw::multibuf::v1_adapter::MultiBuf::TruncateAfter ( iterator pos )

Truncates the MultiBuf after the current iterator. All bytes following the iterator are removed.

Does not modify the underlying data.

This method will acquire a mutex and is not IRQ safe.

◆ v2()

constexpr v2::TrackedMultiBuf * pw::multibuf::v1_adapter::MultiBuf::v2 ( )

inlineconstexpr

Returns the v2 MultiBuf used to implement both the v1 and v2 APIs.

This can be useful for methods that are only in the v1 API of this type due to name collisions, such as empty(), size(), and Chunks().

for (auto chunk : mb.Chunks() {
  // Iterate over raw chunks of memory as in v1.
}
for (auto chunk : mb.v2().Chunks() {
  // Iterate over non-empty chunks of contiguous memory as in v2.
}

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

pw_multibuf/v1_adapter/public/pw_multibuf/v1_adapter/multibuf.h

Overview

Public Types

Public Member Functions

Static Public Member Functions

Member Function Documentation

◆ begin()

◆ Chunks()

◆ ClaimPrefix()

◆ ClaimSuffix()

◆ ConstChunks()

◆ ContiguousSpan()

◆ CopyFrom()

◆ CopyFromAndTruncate()

◆ CopyTo()

◆ DiscardPrefix()

◆ empty()

◆ end()

◆ FromChunk()

◆ InsertChunk()

◆ IsContiguous()

◆ PushBackChunk()

◆ PushFrontChunk()

◆ PushPrefix()

◆ PushSuffix()

◆ Release()

◆ size()

◆ Slice()

◆ TakeChunk()

◆ TakeFrontChunk()

◆ TakePrefix()

◆ TakeSuffix()

◆ Truncate()

◆ TruncateAfter()

◆ v2()