Overview

Abstract interface for variable-layout memory allocation.

The interface makes no guarantees about its implementation. Consumers of the generic interface must not make any assumptions around allocator behavior, thread safety, or performance.

Inheritance diagram for pw::Allocator:

Public Member Functions
void *	Allocate (Layout layout)

template<typename T , int &... kExplicitGuard, typename... Args>
std::enable_if_t<!std::is_array_v< T >, 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 >
T *	NewArray (size_t count)

template<typename T >
T *	NewArray (size_t count, size_t alignment)

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 , int &... kExplicitGuard, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
UniquePtr< T >	MakeUnique (size_t size)

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

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

template<typename T >
UniquePtr< T[]>	MakeUniqueArray (size_t size)

template<typename T >
UniquePtr< T[]>	MakeUniqueArray (size_t size, size_t alignment)

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 , int &... kExplicitGuard, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
SharedPtr< T >	MakeShared (size_t size)

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

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

bool	Resize (void *ptr, size_t new_size)

bool	Resize (void *ptr, Layout layout, size_t new_size)

void *	Reallocate (void *ptr, Layout new_layout)

void *	Reallocate (void *ptr, Layout old_layout, size_t new_size)

size_t	GetAllocated () const

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)

void	Deallocate (void *ptr, Layout layout)

template<typename ElementType >
void	DeleteArray (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 Member Functions
constexpr	Allocator ()=default
	TODO(b/326509341): Remove when downstream consumers migrate.

constexpr	Allocator (const Capabilities &capabilities)

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

constexpr	Deallocator (const Capabilities &capabilities)

template<typename T , int &... kExplicitGuard, typename ElementType = std::remove_extent_t<T>, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
UniquePtr< T >	WrapUnique (ElementType *ptr, size_t size)

Private Member Functions
virtual void *	DoAllocate (Layout layout)=0

virtual bool	DoResize (void *ptr, size_t new_size)

virtual bool	DoResize (void *, Layout, size_t)

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

virtual void *	DoReallocate (void *ptr, Layout old_layout, size_t new_size)

virtual size_t	DoGetAllocated () const

Additional Inherited Members
Public Types inherited from pw::Deallocator
using	Capabilities = allocator::Capabilities

using	Capability = allocator::Capability

using	Layout = allocator::Layout

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

template<typename T >
static constexpr bool	is_unbounded_array_v

Member Function Documentation

◆ Allocate()

void * pw::Allocator::Allocate ( Layout layout )

inline

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.

◆ DoAllocate()

virtual void * pw::Allocator::DoAllocate ( Layout layout )

privatepure virtual

Virtual Allocate function implemented by derived classes.

Parameters

[in] layout Describes the memory to be allocated. Guaranteed to have a non-zero size.

Implemented in pw::allocator::BlockAllocator< BlockType_ >, pw::allocator::BlockAllocator< BestFitBlock< uintptr_t > >, pw::allocator::BlockAllocator< BucketBlock<> >, pw::allocator::BlockAllocator< DlBlock< uintptr_t > >, pw::allocator::BlockAllocator< FirstFitBlock< uintptr_t > >, pw::allocator::BlockAllocator< TlsfBlock< uint32_t > >, pw::allocator::BlockAllocator< WorstFitBlock< uintptr_t > >, pw::allocator::BuddyAllocator< kMinOuterSize_, kNumBuckets >, pw::allocator::BumpAllocator, pw::allocator::FallbackAllocator, pw::allocator::test::FaultInjectingAllocator, pw::allocator::GuardedAllocator< BlockAllocatorType, LockType >, pw::allocator::LibCAllocator, pw::allocator::SynchronizedAllocator< LockType >, pw::allocator::SynchronizedAllocator< pw::sync::Mutex >, pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType >, pw::allocator::test::AllocatorForTest< 1024 >, pw::allocator::TrackingAllocator< MetricsType >, pw::allocator::TrackingAllocator< internal::AllMetrics >, and pw::allocator::NullAllocator.

◆ DoGetAllocated()

virtual size_t pw::Allocator::DoGetAllocated ( ) const

inlineprivatevirtual

Virtual GetAllocated function that can be overridden by derived classes.

The default implementation simply returns size_t(-1), indicating that tracking total allocated bytes is not supported.

Reimplemented in pw::allocator::BlockAllocator< BlockType_ >, pw::allocator::BlockAllocator< BestFitBlock< uintptr_t > >, pw::allocator::BlockAllocator< BucketBlock<> >, pw::allocator::BlockAllocator< DlBlock< uintptr_t > >, pw::allocator::BlockAllocator< FirstFitBlock< uintptr_t > >, pw::allocator::BlockAllocator< TlsfBlock< uint32_t > >, pw::allocator::BlockAllocator< WorstFitBlock< uintptr_t > >, pw::allocator::BumpAllocator, pw::allocator::FallbackAllocator, pw::allocator::SynchronizedAllocator< LockType >, pw::allocator::SynchronizedAllocator< pw::sync::Mutex >, pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType >, pw::allocator::test::AllocatorForTest< 1024 >, pw::allocator::TrackingAllocator< MetricsType >, and pw::allocator::TrackingAllocator< internal::AllMetrics >.

◆ DoReallocate() [1/2]

virtual void * pw::Allocator::DoReallocate	(	void *	ptr,
		Layout	new_layout
	)

privatevirtual

Virtual Reallocate function that can be overridden by derived classes.

The default implementation will first try to Resize the data. If that is unsuccessful, it will allocate an entirely new block, copy existing data, and deallocate the given block.

Parameters

[in]	ptr	Pointer to memory, guaranteed to not be null.
[in]	new_layout	Describes the memory to be allocated. Guaranteed to have a non-zero size.

Reimplemented in pw::allocator::test::FaultInjectingAllocator, pw::allocator::LibCAllocator, pw::allocator::SynchronizedAllocator< LockType >, pw::allocator::SynchronizedAllocator< pw::sync::Mutex >, pw::allocator::TrackingAllocator< MetricsType >, and pw::allocator::TrackingAllocator< internal::AllMetrics >.

◆ DoReallocate() [2/2]

virtual void * pw::Allocator::DoReallocate	(	void *	ptr,
		Layout	old_layout,
		size_t	new_size
	)

privatevirtual

Deprecated version of DoReallocate that takes a Layout. Do not use this method. It will be removed. TODO(b/326509341): Remove when downstream consumers migrate.

◆ DoResize() [1/2]

virtual bool pw::Allocator::DoResize	(	void *	,
		Layout	,
		size_t
	)

inlineprivatevirtual

Deprecated version of DoResize that takes a Layout. Do not use this method. It will be removed. TODO(b/326509341): Remove when downstream consumers migrate.

◆ DoResize() [2/2]

virtual bool pw::Allocator::DoResize	(	void *	ptr,
		size_t	new_size
	)

inlineprivatevirtual

Virtual Resize function implemented by derived classes.

The default implementation simply returns false, indicating that resizing is not supported.

Parameters

[in]	ptr	Pointer to memory, guaranteed to not be null.
[in]	new_size	Requested size, guaranteed to be non-zero..

Reimplemented in pw::allocator::BlockAllocator< BlockType_ >, pw::allocator::BlockAllocator< BestFitBlock< uintptr_t > >, pw::allocator::BlockAllocator< BucketBlock<> >, pw::allocator::BlockAllocator< DlBlock< uintptr_t > >, pw::allocator::BlockAllocator< FirstFitBlock< uintptr_t > >, pw::allocator::BlockAllocator< TlsfBlock< uint32_t > >, pw::allocator::BlockAllocator< WorstFitBlock< uintptr_t > >, pw::allocator::FallbackAllocator, pw::allocator::test::FaultInjectingAllocator, pw::allocator::GuardedAllocator< BlockAllocatorType, LockType >, pw::allocator::SynchronizedAllocator< LockType >, pw::allocator::SynchronizedAllocator< pw::sync::Mutex >, pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType >, pw::allocator::test::AllocatorForTest< 1024 >, pw::allocator::TrackingAllocator< MetricsType >, and pw::allocator::TrackingAllocator< internal::AllMetrics >.

◆ GetAllocated()

size_t pw::Allocator::GetAllocated ( ) const

inline

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.

◆ MakeShared() [1/4]

template<typename T , int &... kExplicitGuard, std::enable_if_t< is_bounded_array_v< T >, int > = 0>

SharedPtr< T > pw::Allocator::MakeShared ( )

inline

Constructs an alignment-byte aligned array of size objects, and wraps it in a SharedPtr

The returned value may contain null if allocating memory for the object fails. Callers must check for null before using the SharedPtr.

Template Parameters

T	An array type.

Parameters

[in]	size	Number of objects to allocate.
[in]	alignment	Object alignment.

◆ MakeShared() [2/4]

template<typename T , int &... kExplicitGuard, std::enable_if_t<!std::is_array_v< T >, int > = 0, typename... Args>

SharedPtr< T > pw::Allocator::MakeShared ( Args &&... args )

inline

Constructs and object of type T from the given args, and wraps it in a SharedPtr

The returned value may contain null if allocating memory for the object fails. Callers must check for null before using the SharedPtr.

Parameters

[in] args Arguments passed to the object constructor.

◆ MakeShared() [3/4]

template<typename T , int &... kExplicitGuard, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>

SharedPtr< T > pw::Allocator::MakeShared ( size_t size )

inline

Constructs an array of size objects, and wraps it in a UniquePtr

The returned value may contain null if allocating memory for the object fails. Callers must check for null before using the UniquePtr.

Template Parameters

T	An array type.

Parameters

[in] size Number of objects to allocate.

◆ MakeShared() [4/4]

template<typename T , int &... kExplicitGuard, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>

SharedPtr< T > pw::Allocator::MakeShared	(	size_t	size,
		size_t	alignment
	)

inline

Constructs an alignment-byte aligned array of size objects, and wraps it in a SharedPtr

The returned value may contain null if allocating memory for the object fails. Callers must check for null before using the SharedPtr.

Template Parameters

T	An array type.

Parameters

[in]	size	Number of objects to allocate.
[in]	alignment	Object alignment.

◆ MakeUnique() [1/4]

template<typename T , int &... kExplicitGuard, std::enable_if_t< is_bounded_array_v< T >, int > = 0>

UniquePtr< T > pw::Allocator::MakeUnique ( )

inline

Constructs an array of objects and wraps it in a UniquePtr.

The returned value may contain null if allocating memory for the object fails. Callers must check for null before using the UniquePtr.

Template Parameters

T	A bounded array type, like `int[3]`.

◆ MakeUnique() [2/4]

template<typename T , int &... kExplicitGuard, std::enable_if_t<!std::is_array_v< T >, int > = 0, typename... Args>

UniquePtr< T > pw::Allocator::MakeUnique ( Args &&... args )

inline

Constructs and object of type T from the given args, and wraps it in a UniquePtr

The returned value may contain null if allocating memory for the object fails. Callers must check for null before using the UniquePtr.

Template Parameters

T	A non-array object type, like `int`.

Parameters

[in] args Arguments passed to the object constructor.

◆ MakeUnique() [3/4]

template<typename T , int &... kExplicitGuard, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>

UniquePtr< T > pw::Allocator::MakeUnique ( size_t size )

inline

Constructs an array of size objects, and wraps it in a UniquePtr

The returned value may contain null if allocating memory for the object fails. Callers must check for null before using the UniquePtr.

Template Parameters

T	An unbounded array type, like `int[]`.

Parameters

[in] size Number of objects to allocate.

◆ MakeUnique() [4/4]

template<typename T , int &... kExplicitGuard, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>

UniquePtr< T > pw::Allocator::MakeUnique	(	size_t	size,
		size_t	alignment
	)

inline

Constructs an alignment-byte aligned array of size objects and wraps it in a UniquePtr.

The returned value may contain null if allocating memory for the object fails. Callers must check for null before using the UniquePtr.

Template Parameters

T	An unbounded array type, like `int[]`.

Parameters

[in]	size	Number of objects to allocate.
[in]	alignment	Object alignment.

◆ MakeUniqueArray() [1/2]

template<typename T >

UniquePtr< T[]> pw::Allocator::MakeUniqueArray ( size_t size )

inline

Deprecated version of MakeUnique with a different name and templated on the object type instead of the array type. Do not use this method. It will be removed. TODO(b/326509341): Remove when downstream consumers migrate.

◆ MakeUniqueArray() [2/2]

template<typename T >

UniquePtr< T[]> pw::Allocator::MakeUniqueArray	(	size_t	size,
		size_t	alignment
	)

inline

Deprecated version of MakeUnique with a different name and templated on the object type instead of the array type. Do not use this method. It will be removed. TODO(b/326509341): Remove when downstream consumers migrate.

◆ New() [1/4]

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

ElementType * pw::Allocator::New ( )

inline

Constructs an array of objects.

The return value is nullable, as allocating memory for the object may fail. Callers must check for this error before using the resulting pointer.

Template Parameters

T	A bounded array type, like `int[3]`.

Parameters

[in] count Number of objects to allocate.

◆ New() [2/4]

template<typename T , int &... kExplicitGuard, typename... Args>

std::enable_if_t<!std::is_array_v< T >, T * > pw::Allocator::New ( Args &&... args )

inline

Constructs an object of type T from the given args.

The return value is nullable, as allocating memory for the object may fail. Callers must check for this error before using the resulting pointer.

Template Parameters

T	A non-array object type, like `int`.

Parameters

[in] args Arguments passed to the object constructor.

◆ New() [3/4]

template<typename T , int &... kExplicitGuard, typename ElementType = std::remove_extent_t<T>, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>

ElementType * pw::Allocator::New ( size_t count )

inline

Constructs an array of count objects.

The return value is nullable, as allocating memory for the object may fail. Callers must check for this error before using the resulting pointer.

Template Parameters

T	An unbounded array type, like `int[]`.

Parameters

[in] count Number of objects to allocate.

◆ New() [4/4]

template<typename T , int &... kExplicitGuard, typename ElementType = std::remove_extent_t<T>, std::enable_if_t< is_unbounded_array_v< T >, int > = 0>

ElementType * pw::Allocator::New	(	size_t	count,
		size_t	alignment
	)

inline

Constructs an alignment-byte aligned array of count objects.

The return value is nullable, as allocating memory for the object may fail. Callers must check for this error before using the resulting pointer.

Template Parameters

T	An unbounded array type, like `int[]`.

Parameters

[in]	count	Number of objects to allocate.
[in]	alignment	Alignment to use for the start of the array.

◆ NewArray() [1/2]

template<typename T >

T * pw::Allocator::NewArray ( size_t count )

inline

Deprecated version of New with a different name and templated on the object type instead of the array type. Do not use this method. It will be removed. TODO(b/326509341): Remove when downstream consumers migrate.

◆ NewArray() [2/2]

template<typename T >

T * pw::Allocator::NewArray	(	size_t	count,
		size_t	alignment
	)

inline

Deprecated version of New with a different name and templated on the object type instead of the array type. Do not use this method. It will be removed. TODO(b/326509341): Remove when downstream consumers migrate.

◆ Reallocate() [1/2]

void * pw::Allocator::Reallocate	(	void *	ptr,
		Layout	new_layout
	)

inline

Modifies the size of a previously-allocated block of memory.

Returns pointer to the modified block of memory, or nullptr if the memory could not be modified.

The data stored by the memory being modified must be trivially copyable. If it is not, callers should themselves attempt to Resize, then Allocate, move the data, and Deallocate as needed.

If nullptr is returned, the block of memory is unchanged. In particular, if the new_layout has a size of 0, the given pointer will NOT be deallocated.

TODO(b/331290408): This error condition needs to be better communicated to module users, who may assume the pointer is freed.

Unlike Resize, providing a null pointer will return a new allocation.

If the request can be satisfied using Resize, the alignment parameter may be ignored.

Parameters

[in]	ptr	Pointer to previously-allocated memory.
[in]	new_layout	Describes the memory to be allocated.

◆ Reallocate() [2/2]

void * pw::Allocator::Reallocate	(	void *	ptr,
		Layout	old_layout,
		size_t	new_size
	)

inline

Deprecated version of Reallocate that takes a Layout. Do not use this method. It will be removed. TODO(b/326509341): Remove when downstream consumers migrate.

◆ Resize() [1/2]

bool pw::Allocator::Resize	(	void *	ptr,
		Layout	layout,
		size_t	new_size
	)

inline

Deprecated version of Resize that takes a Layout. Do not use this method. It will be removed. TODO(b/326509341): Remove when downstream consumers migrate.

◆ Resize() [2/2]

bool pw::Allocator::Resize	(	void *	ptr,
		size_t	new_size
	)

inline

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.

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

pw_allocator/public/pw_allocator/allocator.h

Overview

Public Member Functions

Protected Member Functions

Private Member Functions

Additional Inherited Members

Member Function Documentation

◆ Allocate()

◆ DoAllocate()

◆ DoGetAllocated()

◆ DoReallocate() [1/2]

◆ DoReallocate() [2/2]

◆ DoResize() [1/2]

◆ DoResize() [2/2]

◆ GetAllocated()

◆ MakeShared() [1/4]

◆ MakeShared() [2/4]

◆ MakeShared() [3/4]

◆ MakeShared() [4/4]

◆ MakeUnique() [1/4]

◆ MakeUnique() [2/4]

◆ MakeUnique() [3/4]

◆ MakeUnique() [4/4]

◆ MakeUniqueArray() [1/2]

◆ MakeUniqueArray() [2/2]

◆ New() [1/4]

◆ New() [2/4]

◆ New() [3/4]

◆ New() [4/4]

◆ NewArray() [1/2]

◆ NewArray() [2/2]

◆ Reallocate() [1/2]

◆ Reallocate() [2/2]

◆ Resize() [1/2]

◆ Resize() [2/2]