pw::multibuf::MultiBufAllocator Class Reference

#include <allocator.h>

Inheritance diagram for pw::multibuf::MultiBufAllocator:

Public Member Functions
	MultiBufAllocator (MultiBufAllocator &)=delete
	`MultiBufAllocator is not copyable or movable.
MultiBufAllocator &	operator= (MultiBufAllocator &)=delete
	MultiBufAllocator (MultiBufAllocator &&)=delete
MultiBufAllocator &	operator= (MultiBufAllocator &&)=delete
std::optional< MultiBuf >	Allocate (size_t size)
std::optional< MultiBuf >	Allocate (size_t min_size, size_t desired_size)
std::optional< MultiBuf >	AllocateContiguous (size_t size)
std::optional< MultiBuf >	AllocateContiguous (size_t min_size, size_t desired_size)
std::optional< size_t >	GetBackingCapacity ()

Protected Member Functions
void	MoreMemoryAvailable (size_t size_available, size_t contiguous_size_available)

Private Member Functions
virtual pw::Result< MultiBuf >	DoAllocate (size_t min_size, size_t desired_size, ContiguityRequirement contiguity_requirement)=0
virtual std::optional< size_t >	DoGetBackingCapacity ()=0

Friends
class	MultiBufAllocationFuture

Detailed Description

Interface for allocating MultiBuf objects.

A MultiBufAllocator differs from a regular pw::allocator::Allocator in that they may provide support for:

• Asynchronous allocation.
• Non-contiguous buffer allocation.
• Internal header/footer reservation.
• Size-range allocation.

In order to accomplish this, they return MultiBuf objects rather than arbitrary pieces of memory.

Additionally, MultiBufAllocator implementations may choose to store their allocation metadata separately from the data itself. This allows for things like allocation headers to be kept out of restricted DMA-capable or shared-memory regions.

NOTE: MultiBufAllocators must outlive any futures created from them.

Member Function Documentation

Allocate() [1/2]

std::optional< MultiBuf > pw::multibuf::MultiBufAllocator::Allocate	(	size_t	min_size,
		size_t	desired_size
	)

Attempts to allocate a MultiBuf of at least min_size bytes and at most desired_size bytes.

Memory allocated by an arbitrary MultiBufAllocator does not provide any alignment requirements, preferring instead to allow the allocator maximum flexibility for placing regions (especially discontiguous regions).

Return values

``MultiBuf``	if the allocation was successful.
``nullopt_t``	if the memory is not currently available.

Allocate() [2/2]

std::optional< MultiBuf > pw::multibuf::MultiBufAllocator::Allocate

(

size_t

size

)

Attempts to allocate a MultiBuf of exactly size bytes.

Memory allocated by an arbitrary MultiBufAllocator does not provide any alignment requirements, preferring instead to allow the allocator maximum flexibility for placing regions (especially discontiguous regions).

Return values

``MultiBuf``	if the allocation was successful.
``nullopt_t``	if the memory is not currently available.

AllocateContiguous() [1/2]

std::optional< MultiBuf > pw::multibuf::MultiBufAllocator::AllocateContiguous	(	size_t	min_size,
		size_t	desired_size
	)

Attempts to allocate a contiguous MultiBuf of at least min_size bytes and at most desired_size bytes.

Memory allocated by an arbitrary MultiBufAllocator does not provide any alignment requirements, preferring instead to allow the allocator maximum flexibility for placing regions (especially discontiguous regions).

Return values

``MultiBuf``	with a single Chunk if the allocation was successful.
``nullopt_t``	if the memory is not currently available.

AllocateContiguous() [2/2]

std::optional< MultiBuf > pw::multibuf::MultiBufAllocator::AllocateContiguous

(

size_t

size

)

Attempts to allocate a contiguous MultiBuf of exactly size bytes.

Memory allocated by an arbitrary MultiBufAllocator does not provide any alignment requirements, preferring instead to allow the allocator maximum flexibility for placing regions (especially discontiguous regions).

Return values

``MultiBuf``	with a single Chunk if the allocation was successful.
``nullopt_t``	if the memory is not currently available.

DoAllocate()

virtual pw::Result< MultiBuf > pw::multibuf::MultiBufAllocator::DoAllocate ( size_t  min_size, size_t  desired_size, ContiguityRequirement  contiguity_requirement  )

privatepure virtual

Attempts to allocate a MultiBuf of at least min_size bytes and at most desired_size bytes.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: Returns the buffer if the allocation was successful.
* 
*     RESOURCE_EXHAUSTED: Insufficient memory is available currently.
* 
*     OUT_OF_RANGE: This amount of memory will not become possible to
*     allocate in the future, or this allocator is unable to signal via
*     ``MoreMemoryAvailable`` (this will result in asynchronous allocations
*     failing immediately on OOM).
* 
*  

Implemented in pw::multibuf::SimpleAllocator.

DoGetBackingCapacity()

virtual std::optional< size_t > pw::multibuf::MultiBufAllocator::DoGetBackingCapacity ( )

privatepure virtual

Returns the total amount of memory provided by this object.

This is an optional method. Some memory providers may not have an easily defined capacity, e.g. the system allocator.

Return values

the	total memory if known.
``nullopt_t``	if the total memory is not knowable.

Implemented in pw::multibuf::SimpleAllocator.

GetBackingCapacity()

std::optional< size_t > pw::multibuf::MultiBufAllocator::GetBackingCapacity ( )

inline

Returns the total amount of memory provided by this object.

This is an optional method. Some memory providers may not have an easily defined capacity, e.g. the system allocator.

Return values

the	total memory if known.
``nullopt_t``	if the total memory is not knowable.

MoreMemoryAvailable()

void pw::multibuf::MultiBufAllocator::MoreMemoryAvailable ( size_t  size_available, size_t  contiguous_size_available  )

protected

Awakens callers asynchronously waiting for allocations of at most size_available bytes or at most contiguous_size_available contiguous bytes.

This function should be invoked by implementations of MultiBufAllocator when more memory becomes available to allocate.

---

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

• pw_multibuf/public/pw_multibuf/allocator.h