Legacy v1 API

Overview

Interfaces that will eventually be deprecated.

Most users of pw_multibuf will start by allocating a MultiBuf using a MultiBufAllocator class, such as the SimpleAllocator.

A MultiBuf consists of a number of Chunk instances representing contiguous memory regions. A Chunk can be grown or shrunk which allows MultiBuf to be grown or shrunk. This allows, for example, lower layers to reserve part of a MultiBuf for a header or footer. See Chunk for more details.

MultiBuf exposes an std::byte iterator interface as well as a Chunk iterator available through the Chunks() method. It allows extracting a Chunk as an RAII-style OwnedChunk which manages its own lifetime.

Submodules
	Allocator implementation API
	Test-only features

Classes
class	pw::multibuf::MultiBufAllocator
class	pw::multibuf::MultiBufAllocatorAsync
class	pw::multibuf::MultiBufAllocationFuture
class	pw::multibuf::Chunk
class	pw::multibuf::ChunkRegionTracker
class	pw::multibuf::OwnedChunk
class	pw::multibuf::MultiBufChunks
	A Chunk-oriented view of a MultiBuf. More...
class	pw::multibuf::MultiBuf
class	pw::multibuf::SimpleAllocator
	A simple first-fit MultiBufAllocator. More...
class	pw::multibuf::Stream

Functions
std::optional< MultiBuf >	pw::multibuf::FromSpan (pw::Allocator &metadata_allocator, ByteSpan region, pw::Function< void(ByteSpan)> &&deleter)

Variables
constexpr ContiguityRequirement	pw::multibuf::kAllowDiscontiguous
constexpr ContiguityRequirement	pw::multibuf::kNeedsContiguous

Function Documentation

FromSpan()

std::optional< MultiBuf > pw::multibuf::FromSpan	(	pw::Allocator &	metadata_allocator,
		ByteSpan	region,
		pw::Function< void(ByteSpan)> &&	deleter
	)

Creates a multibuf from an existing span and a deleter callback.

The provided allocator is used to allocate storage for the chunk-tracking metadata. The allocator's lifetime must outlive the returned MultiBuf.

Returns nullopt if the metadata_allocator fails to allocate a metadata region to track the provided buffer. In this case, deleter will not be invoked and the caller will retain ownership of the provided region.

Variable Documentation

kAllowDiscontiguous

constexpr ContiguityRequirement pw::multibuf::kAllowDiscontiguous

inlineconstexpr

Initial value:

=
    ContiguityRequirement::kAllowDiscontiguous

kNeedsContiguous

constexpr ContiguityRequirement pw::multibuf::kNeedsContiguous

inlineconstexpr

Initial value:

=
    ContiguityRequirement::kNeedsContiguous