Pigweed
C/C++ API Reference
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Private Member Functions | List of all members
pw::Allocator Class Referenceabstract
Inheritance diagram for pw::Allocator:
pw::Deallocator pw::allocator::SynchronizedAllocator< pw::sync::Mutex > pw::allocator::TrackingAllocator< internal::AllMetrics > pw::allocator::test::AllocatorForTest< 1024 > pw::allocator::BuddyAllocator< kMinOuterSize_, kNumBuckets > pw::allocator::BumpAllocator pw::allocator::FallbackAllocator pw::allocator::LibCAllocator pw::allocator::NullAllocator pw::allocator::SynchronizedAllocator< LockType > pw::allocator::TrackingAllocator< MetricsType > pw::allocator::internal::GenericBlockAllocator pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType > pw::allocator::test::FaultInjectingAllocator

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 Capabilitiescapabilities () 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
 
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
 

Detailed Description

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.

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]layoutDescribes the memory to be allocated.

◆ DoAllocate()

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

◆ DoGetAllocated()

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

◆ 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]ptrPointer to memory, guaranteed to not be null.
[in]new_layoutDescribes 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

◆ 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
TAn array type.
Parameters
[in]sizeNumber of objects to allocate.
[in]alignmentObject 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]argsArguments 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
TAn array type.
Parameters
[in]sizeNumber 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
TAn array type.
Parameters
[in]sizeNumber of objects to allocate.
[in]alignmentObject 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
TA 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
TA non-array object type, like int.
Parameters
[in]argsArguments 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
TAn unbounded array type, like int[].
Parameters
[in]sizeNumber 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
TAn unbounded array type, like int[].
Parameters
[in]sizeNumber of objects to allocate.
[in]alignmentObject 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
TA bounded array type, like int[3].
Parameters
[in]countNumber 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
TA non-array object type, like int.
Parameters
[in]argsArguments 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
TAn unbounded array type, like int[].
Parameters
[in]countNumber 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
TAn unbounded array type, like int[].
Parameters
[in]countNumber of objects to allocate.
[in]alignmentAlignment 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]ptrPointer to previously-allocated memory.
[in]new_layoutDescribes 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]ptrPointer to previously-allocated memory.
[in]new_sizeRequested new size for the memory allocation.

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