Overview

A handle to a contiguous slice of data that mimics v1::Chunk.

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

A limitation of v1_adapter chunks is that thay do not track unique ownership of a subregion of memory. This means two chunks created from the same region of memory, e.g. via TakePrefix and TakeSuffix, may be able to extend the memory they refer to, e.g. via ClaimPrefix and ClaimSuffix, to include memory referred to by another chunk.

Any calls to these methods that would succeed in v1 will still succeed, but calls of the type described above which would fail in v1 may succeed with this adapter.

Public Types
using	element_type = std::byte

using	value_type = std::byte

using	size_type = size_t

using	difference_type = ptrdiff_t

using	pointer = std::byte *

using	const_pointer = const std::byte *

using	reference = std::byte &

using	const_reference = const std::byte &

using	iterator = std::byte *

using	const_iterator = const std::byte *

using	reverse_iterator = std::byte *

using	const_reverse_iterator = const std::byte *

Public Member Functions
	Chunk (const Chunk &other)

Chunk &	operator= (const Chunk &other)

std::byte *	data ()

const std::byte *	data () const

size_t	size () const

bool	empty () const

std::byte &	operator[] (size_t index)

const std::byte &	operator[] (size_t index) const

constexpr Allocator *	metadata_allocator () const

constexpr const SharedPtr< std::byte[]> &	region () const

std::byte *	begin ()

const std::byte *	begin () const

const std::byte *	cbegin () const

std::byte *	end ()

const std::byte *	end () const

const std::byte *	cend () const

bool	CanMerge (const Chunk &next_chunk) const

bool	Merge (OwnedChunk &next_chunk)

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)

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

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

Friends
class	OwnedChunk

class	MultiBufChunks

Member Function Documentation

◆ CanMerge()

bool pw::multibuf::v1_adapter::Chunk::CanMerge ( const Chunk & next_chunk ) const

Returns if next_chunk is mergeable into the end of this Chunk.

This will only succeed when the two Chunk s are adjacent in memory and originated from the same region.

◆ ClaimPrefix()

bool pw::multibuf::v1_adapter::Chunk::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 this Chunk points to a section of a region that has unreferenced bytes preceding it. For example, a Chunk which has been shrunk using DiscardPrefix can be re-expanded using ClaimPrefix.

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

Warning: See the note about subregion ownership in the class comments.

◆ ClaimSuffix()

bool pw::multibuf::v1_adapter::Chunk::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 this Chunk points to a section of a region that has unreferenced bytes following it. For example, a Chunk which has been shrunk using Truncate can be re-expanded using

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

Warning: See the note about subregion ownership in the class comments.

◆ DiscardPrefix()

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

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 this Chunk points to a section of a region that has unreferenced bytes following it. For example, a Chunk which has been shrunk using Truncate can be re-expanded using

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

Warning: See the note about subregion ownership in the class comments.

◆ Merge()

bool pw::multibuf::v1_adapter::Chunk::Merge ( OwnedChunk & next_chunk )

Attempts to merge next_chunk into the end of this Chunk.

If the chunks are successfully merged, this Chunk will be extended forwards to encompass the space of next_chunk, and next_chunk will be emptied and Released.

This will only succeed when the two Chunk s are adjacent in memory and originated from the same region.

If the chunks are not mergeable, neither Chunk will be modified.

◆ metadata_allocator()

constexpr Allocator * pw::multibuf::v1_adapter::Chunk::metadata_allocator ( ) const

inlineconstexpr

Returns the allocator used to manage metadata memory.

This method does not match any in v1::Chunk, and is used by other v1_adapter types.

◆ region()

constexpr const SharedPtr< std::byte[]> & pw::multibuf::v1_adapter::Chunk::region ( ) const

inlineconstexpr

Returns the shared memory region backing this chunk.

This method does not match any in v1::Chunk, and is used by other v1_adapter types.

◆ Slice()

void pw::multibuf::v1_adapter::Chunk::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.

Warning: See the note about subregion ownership in the class comments.

◆ TakePrefix()

std::optional< OwnedChunk > pw::multibuf::v1_adapter::Chunk::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 OwnedChunk.

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.

Warning: See the note about subregion ownership in the class comments.

◆ TakeSuffix()

std::optional< OwnedChunk > pw::multibuf::v1_adapter::Chunk::TakeSuffix ( 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 OwnedChunk.

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.

Warning: See the note about subregion ownership in the class comments.

◆ Truncate()

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

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.

Warning: See the note about subregion ownership in the class comments.

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

pw_multibuf/v1_adapter/public/pw_multibuf/v1_adapter/chunk.h

Overview

Public Types

Public Member Functions

Friends

Member Function Documentation

◆ CanMerge()

◆ ClaimPrefix()

◆ ClaimSuffix()

◆ DiscardPrefix()

◆ Merge()

◆ metadata_allocator()

◆ region()

◆ Slice()

◆ TakePrefix()

◆ TakeSuffix()

◆ Truncate()