Overview

An allocator that is implemented by forwarding calls to another allocator.

This type can be used as a generic base type for forwarding allocators that provide additional behavior to another allocator. It provides default implementations of the virtual methods from Deallocator and Allocator, allowing authors of derived types to avoid boilerplate.

Note: It is an error for a derived type to override any of the methods below with an implementation that calls any of the corresponding public methods. If it does, the public, NVI-style method will dispatch to the derived type's override, leading to an infinite recursion. Instead, use the allocator accessor or call this type's implementation methods directly:

class MyAllocator : public pw::allocator::ForwardingAllocator {
 private:
  void* Allocate(pw::allocator::Layout layout) override {
    // INCORRECT! This will infinitely recurse.
    // return pw::allocator::ForwardingAllocator::Allocate(layout);
 
    // Correct: This dispatches to the wrapped allocator.
    return allocator().Allocate(layout);
  }
 
  void Deallocate(void* ptr) override {
    // Also correct: This dispatches to the wrapped allocator.
    pw::allocator::ForwardingAllocator::DoDeallocate(ptr);
  }
}

Inheritance diagram for pw::allocator::ForwardingAllocator:

Protected Member Functions
constexpr	ForwardingAllocator (const Capabilities &capabilities) noexcept

constexpr	ForwardingAllocator (pw::Allocator &allocator) noexcept

constexpr void	Init (pw::Allocator &allocator)

constexpr pw::Allocator &	allocator ()

constexpr const pw::Allocator &	allocator () const

void *	DoAllocate (Layout layout) override

void	DoDeallocate (void *ptr) override

bool	DoResize (void *ptr, size_t new_size) override

void	DoBeforeReallocate (void *ptr, Layout new_layout) override

void	DoAfterReallocateCopy (void ptr, Layout new_layout, void new_ptr) override

void	DoAfterReallocateDone (Layout new_layout, void *new_ptr) override

size_t	DoGetAllocated () const override

std::optional< Fragmentation >	DoMeasureFragmentation () const override
	Returns fragmentation information for the allocator's memory region.

Result< Layout >	DoGetInfo (InfoType info_type, const void *ptr) const override

Protected Member Functions inherited from pw::Allocator
constexpr	Allocator () noexcept=default
	TODO(b/326509341): Remove when downstream consumers migrate.

constexpr	Allocator (const Capabilities &capabilities) noexcept

virtual void *	DoAllocate (Layout layout)=0

virtual bool	DoResize (void *ptr, size_t new_size)

virtual void *	DoReallocate (void *ptr, Layout new_layout)

virtual void	DoBeforeReallocate (void *ptr, Layout new_layout)

virtual void	DoAfterReallocateCopy (void ptr, Layout new_layout, void new_ptr)

virtual void	DoAfterReallocateDone (Layout new_layout, void *new_ptr)

virtual size_t	DoGetAllocated () const

virtual std::optional< Fragmentation >	DoMeasureFragmentation () const
	Returns fragmentation information for the allocator's memory region.

Protected Member Functions inherited from pw::Deallocator
constexpr	Deallocator ()=default
	TODO(b/326509341): Remove when downstream consumers migrate.

constexpr	Deallocator (const Capabilities &capabilities)

Result< Layout >	GetInfo (InfoType info_type, const void *ptr) const

Result< Layout >	GetRequestedLayout (const void *ptr) const

Result< Layout >	GetUsableLayout (const void *ptr) const

Result< Layout >	GetAllocatedLayout (const void *ptr) const

bool	Recognizes (const void *ptr) const

virtual void	DoDeallocate (void *ptr)=0

virtual Result< Layout >	DoGetInfo (InfoType, const void *) const

Additional Inherited Members
Public Types inherited from pw::Allocator
using	Fragmentation = allocator::Fragmentation

Public Types inherited from pw::Deallocator
using	Capabilities = allocator::Capabilities

using	Capability = allocator::Capability

using	Layout = allocator::Layout

Public Member Functions inherited from pw::Allocator
void *	Allocate (Layout layout)

template<typename T , int &... kExplicitGuard, std::enable_if_t<!std::is_array_v< T >, int > = 0, typename... Args>
T *	New (Args &&... args)

template<typename T , int &... kExplicitGuard, typename ElementType = std::remove_extent_t<T>, std::enable_if_t< is_bounded_array_v< T >, int > = 0>
ElementType *	New ()

template<typename T , int &... kExplicitGuard, typename ElementType = std::remove_extent_t<T>, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
ElementType *	New (size_t count)

template<typename T , int &... kExplicitGuard, typename ElementType = std::remove_extent_t<T>, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
ElementType *	New (size_t count, size_t alignment)
	Constructs an `alignment`-byte aligned array of `count` objects.

template<typename T , int &... kExplicitGuard, std::enable_if_t<!std::is_array_v< T >, int > = 0, typename... Args>
UniquePtr< T >	MakeUnique (Args &&... args)

template<typename T , std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
UniquePtr< T >	MakeUnique (size_t size)

template<typename T , std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
UniquePtr< T >	MakeUnique (size_t size, size_t alignment)

template<typename T , std::enable_if_t< is_bounded_array_v< T >, int > = 0>
UniquePtr< T >	MakeUnique ()

template<typename T , int &... kExplicitGuard, std::enable_if_t<!std::is_array_v< T >, int > = 0, typename... Args>
SharedPtr< T >	MakeShared (Args &&... args)

template<typename T , std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
SharedPtr< T >	MakeShared (size_t size)

template<typename T , std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
SharedPtr< T >	MakeShared (size_t size, size_t alignment)

template<typename T , std::enable_if_t< is_bounded_array_v< T >, int > = 0>
SharedPtr< T >	MakeShared ()

bool	Resize (void *ptr, size_t new_size)

void *	Reallocate (void *ptr, Layout new_layout)

size_t	GetAllocated () const

std::optional< Fragmentation >	MeasureFragmentation () const
	Returns fragmentation information for the allocator's memory region.

Public Member Functions inherited from pw::Deallocator
constexpr const Capabilities &	capabilities () const

constexpr bool	HasCapability (Capability capability) const
	Returns whether a given capability is enabled for this object.

void	Deallocate (void *ptr)

template<typename ElementType >
void	DeleteArray (ElementType *ptr, size_t count)

template<typename ElementType >
void	Destroy (ElementType *ptr, size_t count)

StatusWithSize	GetCapacity () const

bool	IsEqual (const Deallocator &other) const

template<typename T , int &... kExplicitGuard, std::enable_if_t<!std::is_array_v< T >, int > = 0>
void	Delete (T *ptr)

template<typename T , int &... kExplicitGuard, typename ElementType = std::remove_extent_t<T>, std::enable_if_t< is_bounded_array_v< T >, int > = 0>
void	Delete (ElementType *ptr)

template<typename T , int &... kExplicitGuard, typename ElementType = std::remove_extent_t<T>, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
void	Delete (ElementType *ptr, size_t count)

Protected Types inherited from pw::Deallocator
enum class	InfoType { kRequestedLayoutOf , kUsableLayoutOf , kAllocatedLayoutOf , kCapacity , kRecognizes }

Static Protected Member Functions inherited from pw::Allocator
static void	BeforeReallocate (Allocator &allocator, void *ptr, Layout new_layout)

static void	AfterReallocateCopy (Allocator &allocator, void ptr, Layout new_layout, void new_ptr)

static void	AfterReallocateDone (Allocator &allocator, Layout new_layout, void *new_ptr)

Static Protected Member Functions inherited from pw::Deallocator
static Result< Layout >	GetInfo (const Deallocator &deallocator, InfoType info_type, const void *ptr)

static Result< Layout >	GetRequestedLayout (const Deallocator &deallocator, const void *ptr)

static Result< Layout >	GetUsableLayout (const Deallocator &deallocator, const void *ptr)

static Result< Layout >	GetAllocatedLayout (const Deallocator &deallocator, const void *ptr)

static bool	Recognizes (const Deallocator &deallocator, const void *ptr)

Static Protected Attributes inherited from pw::Deallocator
template<typename T >
static constexpr bool	is_bounded_array_v = ::pw::is_bounded_array_v<T>

template<typename T >
static constexpr bool	is_unbounded_array_v = ::pw::is_unbounded_array_v<T>

Constructor & Destructor Documentation

◆ ForwardingAllocator() [1/2]

constexpr pw::allocator::ForwardingAllocator::ForwardingAllocator ( const Capabilities & capabilities )

inlineexplicitconstexprprotectednoexcept

Creates a forwarding allocator without setting its wrapped allocator.

This constructor should be used when the forwarding allocator needs to be created before the allocator being wrapped. The allocator must be set using Init before any other method is called. The given capabilities must match those of the allocator subsequently provided to Init.

◆ ForwardingAllocator() [2/2]

constexpr pw::allocator::ForwardingAllocator::ForwardingAllocator ( pw::Allocator & allocator )

inlineexplicitconstexprprotectednoexcept

Creates a forwarding allocator that wraps a given allocator.

This constructor should be used when the forwarding allocator is created after the allocator being wrapped.

The allocator must remain valid for the lifetime of this object.

Member Function Documentation

◆ DoAfterReallocateCopy()

void pw::allocator::ForwardingAllocator::DoAfterReallocateCopy	(	void *	ptr,
		Layout	new_layout,
		void *	new_ptr
	)

inlineoverrideprotectedvirtual

Called as part of the default implementation of DoReallocate once the data from ptr has been resized or copied to new_ptr.

By default, does nothing. Derived types may implement this method to add additional behavior. If they do, they must call DoAfterReallocateCopy on their base type before performing any other action.

ptr and new_ptr are guaranteed to be non-null, and new_layout.size() is guaranteed to be non-zero.

Reimplemented from pw::Allocator.

Reimplemented in pw::allocator::FramingAllocator< Prefix, Suffix >.

◆ DoAfterReallocateDone()

void pw::allocator::ForwardingAllocator::DoAfterReallocateDone	(	Layout	new_layout,
		void *	new_ptr
	)

inlineoverrideprotectedvirtual

Called as part of the default implementation of DoReallocate just before returning.

By default, does nothing. Derived types may implement this method to add additional behavior. If they do, they must call DoAfterReallocateDone on their base type before performing any other action.

new_ptr is guaranteed to be non-null, and new_layout.size() is guaranteed to be non-zero.

Reimplemented from pw::Allocator.

Reimplemented in pw::allocator::TrackingAllocator< MetricsType >.

◆ DoAllocate()

void * pw::allocator::ForwardingAllocator::DoAllocate ( Layout layout )

inlineoverrideprotectedvirtual

Allocates a block of memory with the specified size and alignment.

Returns nullptr if the allocation cannot be made, or the layout has a size of 0.

Parameters

[in] layout Describes the memory to be allocated.

Implements pw::Allocator.

Reimplemented in pw::allocator::FramingAllocator< Prefix, Suffix >, pw::allocator::SynchronizedAllocator< LockType >, pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType_ >, and pw::allocator::TrackingAllocator< MetricsType >.

◆ DoBeforeReallocate()

void pw::allocator::ForwardingAllocator::DoBeforeReallocate	(	void *	ptr,
		Layout	new_layout
	)

inlineoverrideprotectedvirtual

Called at the start of the default implementation of DoReallocate.

By default, does nothing. Derived types may implement this method to add additional behavior. If they do, they must call DoBeforeReallocate on their base type just before returning.

ptr is guaranteed to be non-null, and new_layout.size() is guaranteed to be non-zero.

Reimplemented from pw::Allocator.

Reimplemented in pw::allocator::FramingAllocator< Prefix, Suffix >, pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType_ >, and pw::allocator::TrackingAllocator< MetricsType >.

◆ DoDeallocate()

void pw::allocator::ForwardingAllocator::DoDeallocate ( void * ptr )

inlineoverrideprotectedvirtual

Releases a previously-allocated block of memory.

The given pointer must have been previously provided by this memory resource; otherwise the behavior is undefined.

Parameters

[in] ptr Pointer to previously-allocated memory.

Implements pw::Deallocator.

Reimplemented in pw::allocator::FramingAllocator< Prefix, Suffix >, pw::allocator::SynchronizedAllocator< LockType >, pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType_ >, and pw::allocator::TrackingAllocator< MetricsType >.

◆ DoGetAllocated()

size_t pw::allocator::ForwardingAllocator::DoGetAllocated ( ) const

inlineoverrideprotectedvirtual

Returns the total bytes that have been allocated by this allocator, or size_t(-1) if this allocator does not track its total allocated bytes.

Reimplemented from pw::Allocator.

Reimplemented in pw::allocator::SynchronizedAllocator< LockType >.

◆ DoGetInfo()

Result< Layout > pw::allocator::ForwardingAllocator::DoGetInfo	(	InfoType	info_type,
		const void *	ptr
	)		const

inlineoverrideprotectedvirtual

Returns deallocator-specific information about allocations.

Deallocators may support any number of InfoTypes. See that type for what each supported type returns. For unsupported types, this method returns UNIMPLEMENTED.

Reimplemented from pw::Deallocator.

Reimplemented in pw::allocator::FramingAllocator< Prefix, Suffix >, and pw::allocator::SynchronizedAllocator< LockType >.

◆ DoMeasureFragmentation()

std::optional< Fragmentation > pw::allocator::ForwardingAllocator::DoMeasureFragmentation ( ) const

inlineoverrideprotectedvirtual

Returns fragmentation information for the allocator's memory region.

Reimplemented from pw::Allocator.

Reimplemented in pw::allocator::SynchronizedAllocator< LockType >, and pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType_ >.

◆ DoResize()

bool pw::allocator::ForwardingAllocator::DoResize	(	void *	ptr,
		size_t	new_size
	)

inlineoverrideprotectedvirtual

Modifies the size of an previously-allocated block of memory without copying any data.

Returns true if its size was changed without copying data to a new allocation; otherwise returns false.

In particular, it always returns true if the old_layout.size() equals new_size, and always returns false if the given pointer is null, the old_layout.size() is 0, or the new_size is 0.

Parameters

[in]	ptr	Pointer to previously-allocated memory.
[in]	new_size	Requested new size for the memory allocation.

Reimplemented from pw::Allocator.

Reimplemented in pw::allocator::FramingAllocator< Prefix, Suffix >, pw::allocator::SynchronizedAllocator< LockType >, pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType_ >, and pw::allocator::TrackingAllocator< MetricsType >.

◆ Init()

constexpr void pw::allocator::ForwardingAllocator::Init ( pw::Allocator & allocator )

inlineconstexprprotected

Sets the allocator being wrapped.

It is an error to call this method if an allocator was provided to the constructor. The capabilities of the given allocator must match those of previously provided to the constructor.

The allocator must remain valid for the lifetime of this object.

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

pw_allocator/public/pw_allocator/forwarding_allocator.h

Overview

Protected Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ ForwardingAllocator() [1/2]

◆ ForwardingAllocator() [2/2]

Member Function Documentation

◆ DoAfterReallocateCopy()

◆ DoAfterReallocateDone()

◆ DoAllocate()

◆ DoBeforeReallocate()

◆ DoDeallocate()

◆ DoGetAllocated()

◆ DoGetInfo()

◆ DoMeasureFragmentation()

◆ DoResize()

◆ Init()