Implementation interfaces

Oveview

Interfaces for allocator implementers.

These interfaces are intended for allocator implementers, not for pw_allocator consumers.

Submodules
	Size reports
	Generate code size reports for allocator implementations.
	Testing and debugging
	Test utilities for allocator implementers.

Classes
class	pw::allocator::Capabilities
class	pw::Deallocator
	Abstract interface for releasing memory. More...

Typedefs
using	pw::Deallocator::Capabilities = allocator::Capabilities
using	pw::Deallocator::Capability = allocator::Capability
using	pw::Deallocator::Layout = allocator::Layout
using	Capabilities = allocator::Capabilities
using	Capability = allocator::Capability
using	Layout = allocator::Layout
using	allocator::Deallocator = ::pw::Deallocator

Enumerations
enum	pw::allocator::Capability : uint32_t {   kImplementsGetRequestedLayout = 1 << 0 , kImplementsGetUsableLayout = 1 << 1 , kImplementsGetAllocatedLayout = 1 << 2 , kImplementsGetCapacity = 1 << 4 ,   kImplementsRecognizes = 1 << 5 , kSkipsDestroy = 1 << 6 }

Functions
constexpr bool	pw::allocator::operator== (const Capabilities &lhs, const Capabilities &rhs)
constexpr bool	pw::allocator::operator!= (const Capabilities &lhs, const Capabilities &rhs)
constexpr Capabilities	pw::allocator::operator| (const Capabilities &lhs, const Capabilities &rhs)
constexpr Capabilities	pw::allocator::operator& (const Capabilities &lhs, const Capabilities &rhs)
constexpr Capabilities	pw::allocator::operator^ (const Capabilities &lhs, const Capabilities &rhs)
constexpr const Capabilities &	pw::Deallocator::capabilities () const
bool	pw::Deallocator::HasCapability (Capability capability) const
	Returns whether a given capability is enabled for this object.
void	pw::Deallocator::Deallocate (void *ptr)
void	pw::Deallocator::Deallocate (void *ptr, Layout layout)
template<typename ElementType >
void	pw::Deallocator::DeleteArray (ElementType *ptr, size_t count)
StatusWithSize	pw::Deallocator::GetCapacity () const
bool	pw::Deallocator::IsEqual (const Deallocator &other) const
constexpr	pw::Deallocator::Deallocator ()=default
	TODO(b/326509341): Remove when downstream consumers migrate.
constexpr	pw::Deallocator::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 >	pw::Deallocator::WrapUnique (ElementType *ptr, size_t size)
class pw::Deallocator	pw::DoGetInfo (InfoType info_type, const void *ptr) override
constexpr const Capabilities &	capabilities () const
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
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)

Variables
template<typename T >
static constexpr bool	pw::Deallocator::is_bounded_array_v
template<typename T >
static constexpr bool	pw::Deallocator::is_unbounded_array_v
template<typename T >
static constexpr bool	is_bounded_array_v
template<typename T >
static constexpr bool	is_unbounded_array_v
template<typename T , int &... kExplicitGuard, std::enable_if_t<!std::is_array_v< T >, int > = 0>
void	pw::Deallocator::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	pw::Deallocator::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	pw::Deallocator::Delete (ElementType *ptr, size_t count)
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)

Enumeration Type Documentation

Capability

enum pw::allocator::Capability : uint32_t

Hints about optional methods implemented or optional behaviors requested by an allocator of a derived type.

Implementations can provide hints by passing capabilities to the base class constructor. These capabilities can be constructed by combining Capabilitys using logical operations.

Function Documentation

Deallocate() [1/4]

void pw::Deallocator::Deallocate ( void *  ptr )

inline

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.

Deallocate() [2/4]

void DoGetInfo::Deallocate

(

void *

ptr

)

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.

Deallocate() [3/4]

void pw::Deallocator::Deallocate ( void *  ptr, Layout  layout  )

inline

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

Deallocate() [4/4]

void DoGetInfo::Deallocate	(	void *	ptr,
		Layout	layout
	)

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

Delete() [1/2]

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

void pw::Deallocator::Delete ( T *  ptr )

inline

Destroys the object and deallocates the associated memory.

The given pointer must have been previously obtained from a call to New using the same object; otherwise the behavior is undefined.

Warning

As with new/new[] and delete/delete[], it is an error to call a specialization of Delete other than the one that corresponds to the specialization of New that was used to allocate the object.

It is especially important to avoid passing the pointer return by a call to New<T[]> or New<T[kN] to Delete, as this will only delete the first object in the array. For this reason, it is recommended to use DeleteArray or explicitly specify the array type as a template parameter to either Delete<T[]> or Delete<T[kN]>.

Using an allocator with the kImplementsGetRequestedLayout capability and configuring the hardening level to PW_ALLOCATOR_HARDENING_DEBUG will detect such mismatches when Delete is called.

Parameters

[in]

ptr

Pointer to previously-allocated object.

Delete() [2/2]

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

void DoGetInfo::Delete

(

T *

ptr

)

Destroys the object and deallocates the associated memory.

The given pointer must have been previously obtained from a call to New using the same object; otherwise the behavior is undefined.

Warning

As with new/new[] and delete/delete[], it is an error to call a specialization of Delete other than the one that corresponds to the specialization of New that was used to allocate the object.

It is especially important to avoid passing the pointer return by a call to New<T[]> or New<T[kN] to Delete, as this will only delete the first object in the array. For this reason, it is recommended to use DeleteArray or explicitly specify the array type as a template parameter to either Delete<T[]> or Delete<T[kN]>.

Using an allocator with the kImplementsGetRequestedLayout capability and configuring the hardening level to PW_ALLOCATOR_HARDENING_DEBUG will detect such mismatches when Delete is called.

Parameters

[in]

ptr

Pointer to previously-allocated object.

DeleteArray() [1/2]

template<typename ElementType >

void pw::Deallocator::DeleteArray ( ElementType *  ptr, size_t  count  )

inline

Destroys the array and deallocates the associated memory.

The given pointer must be to an array with count elements that was previously obtained from a call to New using the same object; otherwise the behavior is undefined.

This method MUST be used to delete arrays with deallocators that do not have the capability to recover the layout that was used to request memory, i.e. Capability::kImplementsGetRequestedLayout.

Parameters

[in]	ptr	Pointer to previously-allocated array.
[in]	count	Number of items in the array.

DeleteArray() [2/2]

template<typename ElementType >

void DoGetInfo::DeleteArray	(	ElementType *	ptr,
		size_t	count
	)

Destroys the array and deallocates the associated memory.

The given pointer must be to an array with count elements that was previously obtained from a call to New using the same object; otherwise the behavior is undefined.

This method MUST be used to delete arrays with deallocators that do not have the capability to recover the layout that was used to request memory, i.e. Capability::kImplementsGetRequestedLayout.

Parameters

[in]	ptr	Pointer to previously-allocated array.
[in]	count	Number of items in the array.

GetCapacity() [1/2]

StatusWithSize pw::Deallocator::GetCapacity ( ) const

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. If implemented, the returned capacity may be less than the memory originally given to an allocator, e.g. if the allocator must align the region of memory, its capacity may be reduced.

GetCapacity() [2/2]

StatusWithSize DoGetInfo::GetCapacity

(

)

const

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. If implemented, the returned capacity may be less than the memory originally given to an allocator, e.g. if the allocator must align the region of memory, its capacity may be reduced.

IsEqual() [1/2]

bool pw::Deallocator::IsEqual ( const Deallocator &  other ) const

inline

Returns whether the given object is the same as this one.

This method is used instead of operator== in keeping with std::pmr::memory_resource::is_equal. There currently is no corresponding virtual DoIsEqual, as objects that would require dynamic_cast to properly determine equality are not supported. This method will allow the interface to remain unchanged should a future need for such objects arise.

Parameters

[in]

other

Object to compare with this object.

IsEqual() [2/2]

bool DoGetInfo::IsEqual

(

const Deallocator &

other

)

const

Returns whether the given object is the same as this one.

This method is used instead of operator== in keeping with std::pmr::memory_resource::is_equal. There currently is no corresponding virtual DoIsEqual, as objects that would require dynamic_cast to properly determine equality are not supported. This method will allow the interface to remain unchanged should a future need for such objects arise.

Parameters

[in]

other

Object to compare with this object.

WrapUnique() [1/2]

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 > pw::Deallocator::WrapUnique ( ElementType *  ptr, size_t  size  )

inlineprotected

Wraps an array of type T in a UniquePtr

Deprecated:

Construct a UniquePtr<T> directly instead.

TODO(b/326509341): Remove when downstream consumers migrate.

Parameters

[in]	ptr	Pointer to memory provided by this object.
[in]	size	The size of the array.

WrapUnique() [2/2]

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 > DoGetInfo::WrapUnique ( ElementType *  ptr, size_t  size  )

protected

Wraps an array of type T in a UniquePtr

Deprecated:

Construct a UniquePtr<T> directly instead.

TODO(b/326509341): Remove when downstream consumers migrate.

Parameters

[in]	ptr	Pointer to memory provided by this object.
[in]	size	The size of the array.

Variable Documentation

is_bounded_array_v [1/2]

template<typename T >

constexpr bool pw::Deallocator::is_bounded_array_v

staticconstexprprotected

Initial value:

=
      allocator::internal::is_bounded_array_v<T>

is_bounded_array_v [2/2]

template<typename T >

constexpr bool is_bounded_array_v

staticconstexprprotected

Initial value:

=
      allocator::internal::is_bounded_array_v<T>

is_unbounded_array_v [1/2]

template<typename T >

constexpr bool pw::Deallocator::is_unbounded_array_v

staticconstexprprotected

Initial value:

=
      allocator::internal::is_unbounded_array_v<T>

is_unbounded_array_v [2/2]

template<typename T >

constexpr bool is_unbounded_array_v

staticconstexprprotected

Initial value:

=
      allocator::internal::is_unbounded_array_v<T>