Pigweed
Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | List of all members
pw::Allocator Class Referenceabstract

#include <allocator.h>

Public Member Functions

void * Allocate (Layout layout)
 
template<typename T , int &... ExplicitGuard, typename... Args>
T * New (Args &&... args)
 
template<typename T , int &... ExplicitGuard, typename... Args>
UniquePtr< T > MakeUnique (Args &&... args)
 
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)
 
allocator::AsPmrAllocator as_pmr ()
 
- Public Member Functions inherited from pw::Deallocator
const Capabilities & capabilities () const
 
bool HasCapability (Capability capability) const
 Returns whether a given capabilityis enabled for this object.
 
void Deallocate (void *ptr)
 
void Deallocate (void *ptr, Layout layout)
 
template<typename T >
void Delete (T *ptr)
 
StatusWithSize GetCapacity () const
 
bool IsEqual (const Deallocator &other) const
 

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 >
UniquePtr< T > WrapUnique (T *ptr)
 

Additional Inherited Members

- Public Types inherited from pw::Deallocator
using Capabilities = allocator::Capabilities
 
using Capability = allocator::Capability
 
using Layout = allocator::Layout
 

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.

◆ as_pmr()

allocator::AsPmrAllocator pw::Allocator::as_pmr ( )
inline

Returns an std::pmr::polymorphic_allocator that wraps this object.

The returned object can be used with the PMR versions of standard library containers, e.g. std::pmr::vector, std::pmr::string, etc.

embed:rst:leading-asterisk
 
*  See also :ref:`module-pw_allocator-use-standard-library-containers`
*

◆ MakeUnique()

template<typename T , int &... ExplicitGuard, 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.

Parameters
[in]args...Arguments passed to the object constructor.

◆ New()

template<typename T , int &... ExplicitGuard, typename... Args>
T * pw::Allocator::New ( Args &&...  args)
inline

Constructs and 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.

Parameters
[in]args...Arguments passed to the object constructor.

◆ 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: