Overview

Abstract interface for releasing memory.

Inheritance diagram for pw::Deallocator:

Public Types
using	Capabilities = allocator::Capabilities

using	Capability = allocator::Capability

using	Layout = allocator::Layout

Public Member Functions
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)

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
enum class	InfoType { kRequestedLayoutOf , kUsableLayoutOf , kAllocatedLayoutOf , kCapacity , kRecognizes }

Protected Member Functions
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

Static Protected Member Functions
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
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>

Member Enumeration Documentation

◆ InfoType

enum class pw::Deallocator::InfoType

strongprotected

Indicates what kind of information to retrieve using GetInfo.

Note that this enum is considered open, and may be extended in the future. As a result, implementers of DoGetInfo should include a default case that handles unrecognized info types. If building with -Wswitch-enum, you will also want to locally disable that diagnostic and build with -Wswitch-default instead, e.g.:

class MyAllocator : public Allocator {
 private:
  Layout MyGetLayoutFromPointer(const void* ptr) {
    …
  }
 
  Result<Layout> DoGetInfo(InfoType info_type, const void* ptr) override {
    PW_MODIFY_DIAGNOSTICS_PUSH();
    PW_MODIFY_DIAGNOSTIC(ignored, "-Wswitch-enum");
    switch(info_type) {
      case InfoType::kAllocatedLayoutOf:
        return MyGetLayoutFromPointer(ptr);
      default:
        return Status::Unimplmented();
    }
    PW_MODIFY_DIAGNOSTICS_POP();
  }
};

Member Function Documentation

◆ Deallocate()

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.

◆ Delete()

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

void pw::Deallocator::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()

template<typename ElementType >

void pw::Deallocator::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.

◆ DoDeallocate()

virtual void pw::Deallocator::DoDeallocate ( void * ptr )

protectedpure virtual

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.

◆ DoGetInfo()

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

inlineprotectedvirtual

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.

The default implementation simply returns UNIMPLEMENTED.

◆ GetAllocatedLayout() [1/2]

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

inlinestaticprotected

Static version of GetAllocatedLayout that allows forwarding allocators to call it on wrapped allocators.

◆ GetAllocatedLayout() [2/2]

Result< Layout > pw::Deallocator::GetAllocatedLayout ( const void * ptr ) const

inlineprotected

Convenience wrapper of DoGetInfo for getting the allocated layout associated with a pointer.

◆ GetCapacity()

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.

◆ GetInfo() [1/2]

static Result< Layout > pw::Deallocator::GetInfo	(	const Deallocator &	deallocator,
		InfoType	info_type,
		const void *	ptr
	)

inlinestaticprotected

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.

This method is protected in order to restrict it to object implementations. It is static and takes an deallocator parameter in order to allow forwarding allocators to call it on wrapped allocators.

◆ GetInfo() [2/2]

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

inlineprotected

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.

◆ GetRequestedLayout() [1/2]

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

inlinestaticprotected

Static version of GetRequestedLayout that allows forwarding allocators to call it on wrapped allocators.

◆ GetRequestedLayout() [2/2]

Result< Layout > pw::Deallocator::GetRequestedLayout ( const void * ptr ) const

inlineprotected

Convenience wrapper of DoGetInfo for getting the requested layout associated with a pointer.

◆ GetUsableLayout() [1/2]

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

inlinestaticprotected

Static version of GetUsableLayout that allows forwarding allocators to call it on wrapped allocators.

◆ GetUsableLayout() [2/2]

Result< Layout > pw::Deallocator::GetUsableLayout ( const void * ptr ) const

inlineprotected

Convenience wrapper of DoGetInfo for getting the usable layout associated with a pointer.

◆ IsEqual()

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.

◆ Recognizes() [1/2]

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

inlinestaticprotected

Static version of Recognizes that allows forwarding allocators to call it on wrapped allocators.

◆ Recognizes() [2/2]

bool pw::Deallocator::Recognizes ( const void * ptr ) const

inlineprotected

Convenience wrapper of DoGetInfo for getting whether the allocator recognizes a pointer.

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

pw_allocator/public/pw_allocator/deallocator.h

Enumerator
kRequestedLayoutOf	If supported, `GetInfo` will return `OK` with the `Layout` of the requested memory associated with the given pointer, or `NOT_FOUND` if the pointer is not recognized. The requested layout may differ from either the layout of usable memory, the layout of memory used to fulfill the request, or both. For example, it may have a smaller size than the usable memory if the latter was padded to an alignment boundary, or may have a less strict alignment than the actual memory.
kUsableLayoutOf	If supported, `GetInfo` will return `OK` with the `Layout` of the usable memory associated with the given pointer, or `NOT_FOUND` if the pointer is not recognized. The usable layout may from either the requested layout, the layout of memory used to fulfill the request, or both. For example, it may have a larger size than the requested layout if it was padded to an alignment boundary, but may be less than the acutal memory if the object includes some overhead for metadata.
kAllocatedLayoutOf	If supported, `GetInfo` will return `OK` with the `Layout` of the allocated memory associated with the given pointer, or `NOT_FOUND` if the pointer is not recognized. The layout of memory used to fulfill a request may differ from either the requested layout, the layout of the usable memory, or both. For example, it may have a larger size than the requested layout or the layout of usable memory if the object includes some overhead for metadata.
kCapacity	If supported, `GetInfo` will return `OK` with a `Layout` whose size is the total number of bytes that can be allocated by this object, and whose alignment is the minimum alignment of any allocation. The given pointer is ignored.
kRecognizes	If supported, `GetInfo` will return `OK` with a default `Layout` if the given pointer was provided by this object, or `NOT_FOUND`. This MUST only be used to dispatch between two or more objects associated with non-overlapping regions of memory. Do NOT use it to determine if this object can deallocate pointers. Callers MUST only deallocate memory using the same `Deallocator` that provided it.

Overview

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Static Protected Attributes

Member Enumeration Documentation

◆ InfoType

Member Function Documentation

◆ Deallocate()

◆ Delete()

◆ DeleteArray()

◆ DoDeallocate()

◆ DoGetInfo()

◆ GetAllocatedLayout() [1/2]

◆ GetAllocatedLayout() [2/2]

◆ GetCapacity()

◆ GetInfo() [1/2]

◆ GetInfo() [2/2]

◆ GetRequestedLayout() [1/2]

◆ GetRequestedLayout() [2/2]

◆ GetUsableLayout() [1/2]

◆ GetUsableLayout() [2/2]

◆ IsEqual()

◆ Recognizes() [1/2]

◆ Recognizes() [2/2]