Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. Memory & storage
  5. pw_allocator
  6. Forwarding allocators
  7. pw::allocator::TrackingAllocator< MetricsType > Class Template Reference
pw::allocator::TrackingAllocator< MetricsType > Class Template Reference

Overview

template<typename MetricsType>
class pw::allocator::TrackingAllocator< MetricsType >

Wraps an Allocator and records details of its usage.

Metric collection is performed using the provided template parameter type. Callers can not instantiate this class directly, as it lacks a public constructor. Instead, callers should use derived classes which provide the template parameter type, such as TrackingAllocator which uses the default metrics implementation, or TrackingAllocatorForTest which always uses the real metrics implementation.

If the underlying allocator does not have the kImplementsGetAllocatedLayout capability, the peak allocation metric may be lower than the actual peak allocation value. This is because the tracking allocator cannot account for the overlap in memory usage during reallocation when it occurs as a "move-and-copy" operation.

Inheritance diagram for pw::allocator::TrackingAllocator< MetricsType >:
pw::allocator::ForwardingAllocator pw::Allocator pw::Deallocator

Public Member Functions

constexpr TrackingAllocator (metric::Token token, const Capabilities &capabilities) noexcept
 
constexpr TrackingAllocator (metric::Token token, Allocator &allocator, const Capabilities &capabilities)
 
constexpr TrackingAllocator (metric::Token token, Allocator &allocator) noexcept
 
constexpr TrackingAllocator (metric::Token token, const Capabilities &capabilities, metric::GroupList &groups) noexcept
 
constexpr TrackingAllocator (metric::Token token, Allocator &allocator, const Capabilities &capabilities, metric::GroupList &groups)
 
constexpr TrackingAllocator (metric::Token token, Allocator &allocator, metric::GroupList &groups)
 
template<typename OtherMetrics >
constexpr TrackingAllocator (metric::Token token, TrackingAllocator< OtherMetrics > &parent, const AddTrackingAllocatorAsChild &)
 
constexpr void Init (Allocator &allocator)
 
constexpr const metric::Group & metric_group () const
 Returns this tracking allocator's metric group.
 
constexpr metric::Group & metric_group ()
 Returns this tracking allocator's mutable metric group.
 
constexpr const MetricsType & metrics () const
 Returns the metrics struct tracked by this allocator.
 
void UpdateDeferred ()
 
- Public Member Functions inherited from pw::Allocator
void * Allocate (Layout layout)
 
template<typename T , int &... kExplicitGuard, std::enable_if_t<!std::is_array_v< T >, int > = 0, typename... Args>
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 , int &... kExplicitGuard, std::enable_if_t<!std::is_array_v< T >, int > = 0, typename... Args>
UniquePtr< T > MakeUnique (Args &&... args)
 
template<typename T , std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
UniquePtr< T > MakeUnique (size_t size)
 
template<typename T , std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
UniquePtr< T > MakeUnique (size_t size, size_t alignment)
 
template<typename T , std::enable_if_t< is_bounded_array_v< T >, int > = 0>
UniquePtr< T > MakeUnique ()
 
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 , std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
SharedPtr< T > MakeShared (size_t size)
 
template<typename T , std::enable_if_t< is_unbounded_array_v< T >, int > = 0>
SharedPtr< T > MakeShared (size_t size, size_t alignment)
 
template<typename T , std::enable_if_t< is_bounded_array_v< T >, int > = 0>
SharedPtr< T > MakeShared ()
 
bool Resize (void *ptr, size_t new_size)
 
void * Reallocate (void *ptr, Layout new_layout)
 
std::optional< Fragmentation > MeasureFragmentation () const
 Returns fragmentation information for the allocator's memory region.
 
- 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.
 
bool IsEqual (const Deallocator &other) const
 
void Deallocate (void *ptr)
 
template<typename ElementType >
void DeleteArray (ElementType *ptr, size_t count)
 
template<typename ElementType >
void Destroy (ElementType *ptr, size_t count)
 
StatusWithSize GetCapacity () const
 
size_t GetAllocated () const
 
std::optional< size_t > GetAllocatedBytes () 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

void * DoAllocate (Layout layout) override
 
void DoDeallocate (void *ptr) override
 
bool DoResize (void *ptr, size_t new_size) override
 
bool DoBeforeReallocate (void *ptr, Layout new_layout) override
 
void DoAfterReallocateDone (Layout new_layout, void *new_ptr) override
 
- Protected Member Functions inherited from pw::allocator::ForwardingAllocator
constexpr ForwardingAllocator (const Capabilities &capabilities) noexcept
 
constexpr ForwardingAllocator (pw::Allocator &allocator, const Capabilities &capabilities) noexcept
 
constexpr ForwardingAllocator (pw::Allocator &allocator) noexcept
 
constexpr void Init (pw::Allocator &allocator)
 
constexpr pw::Allocator & allocator ()
 
constexpr const pw::Allocator & allocator () const
 
void * DoAllocate (Layout layout) override
 
void DoDeallocate (void *ptr) override
 
bool DoResize (void *ptr, size_t new_size) override
 
bool DoBeforeReallocate (void *ptr, Layout new_layout) override
 
void DoAfterReallocateCopy (void *ptr, Layout new_layout, void *new_ptr) override
 
void DoAfterReallocateDone (Layout new_layout, void *new_ptr) override
 
size_t DoGetAllocated () const override
 
std::optional< size_t > DoGetAllocatedBytes () const override
 
std::optional< Fragmentation > DoMeasureFragmentation () const override
 Returns fragmentation information for the allocator's memory region.
 
Result< Layout > DoGetInfo (InfoType info_type, const void *ptr) const override
 
- Protected Member Functions inherited from pw::Allocator
constexpr Allocator () noexcept=default
 TODO(b/326509341): Remove when downstream consumers migrate.
 
constexpr Allocator (const Capabilities &capabilities) noexcept
 
virtual void * DoAllocate (Layout layout)=0
 
virtual bool DoResize (void *ptr, size_t new_size)
 
virtual void * DoReallocate (void *ptr, Layout new_layout)
 
virtual bool DoBeforeReallocate (void *ptr, Layout new_layout)
 
virtual void DoAfterReallocateCopy (void *ptr, Layout new_layout, void *new_ptr)
 
virtual void DoAfterReallocateDone (Layout new_layout, void *new_ptr)
 
virtual std::optional< Fragmentation > DoMeasureFragmentation () const
 Returns fragmentation information for the allocator's memory region.
 
- Protected Member Functions inherited from pw::Deallocator
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
 
virtual size_t DoGetAllocated () const
 
virtual std::optional< size_t > DoGetAllocatedBytes () 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 info_type, const void *ptr) const
 

Additional Inherited Members

- Public Types inherited from pw::Allocator
using Fragmentation = allocator::Fragmentation
 
- Public Types inherited from pw::Deallocator
using Capabilities = allocator::Capabilities
 
using Capability = allocator::Capability
 
using Layout = allocator::Layout
 
- Static Public Attributes inherited from pw::Deallocator
static constexpr size_t kGetAllocatedUnsupported = size_t(-1)
 
- Protected Types inherited from pw::Deallocator
enum class  InfoType {
  kRequestedLayoutOf , kUsableLayoutOf , kAllocatedLayoutOf , kCapacity ,
  kRecognizes
}
 
- Static Protected Member Functions inherited from pw::Allocator
static bool BeforeReallocate (Allocator &allocator, void *ptr, Layout new_layout)
 
static void AfterReallocateCopy (Allocator &allocator, void *ptr, Layout new_layout, void *new_ptr)
 
static void AfterReallocateDone (Allocator &allocator, Layout new_layout, void *new_ptr)
 
- Static Protected Member Functions inherited from pw::Deallocator
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 inherited from pw::Deallocator
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>
 

Constructor & Destructor Documentation

◆ TrackingAllocator() [1/7]

template<typename MetricsType >
constexpr pw::allocator::TrackingAllocator< MetricsType >::TrackingAllocator ( metric::Token  token,
const Capabilities &  capabilities 
)
inlineexplicitconstexprnoexcept

Constructs a tracking allocator without setting its wrapped allocator.

Init() must be called with the wrapped allocator before any allocation methods are invoked. Can be used with PW_CONSTINIT for two-phase initialization regardless of which metrics MetricsType enables.

Parameters
[in]tokenTokenized name of this allocator's metric group.
[in]capabilitiesCapabilities exposed by this allocator.

◆ TrackingAllocator() [2/7]

template<typename MetricsType >
constexpr pw::allocator::TrackingAllocator< MetricsType >::TrackingAllocator ( metric::Token  token,
Allocator &  allocator,
const Capabilities &  capabilities 
)
inlineconstexpr

Constructs a tracking allocator wrapping allocator with explicit capabilities.

Unlike TrackingAllocator(metric::Token, Allocator&), this constructor does not read allocator.capabilities(), so it can be used with PW_CONSTINIT for single-phase constant initialization when wrapping a separate static allocator and MetricsType only enables counter metrics (i.e. neither requested_bytes nor allocated_bytes is enabled). When requested_bytes or allocated_bytes is enabled, use two-phase initialization via TrackingAllocator(token, capabilities) and Init().

Parameters
[in]tokenTokenized name of this allocator's metric group.
[in,out]allocatorWrapped allocator to forward requests to. Must remain valid for the lifetime of this object.
[in]capabilitiesCapabilities exposed by this allocator.

◆ TrackingAllocator() [3/7]

template<typename MetricsType >
constexpr pw::allocator::TrackingAllocator< MetricsType >::TrackingAllocator ( metric::Token  token,
Allocator &  allocator 
)
inlineconstexprnoexcept

Constructs a tracking allocator wrapping allocator and inheriting allocator.capabilities().

Parameters
[in]tokenTokenized name of this allocator's metric group.
[in,out]allocatorWrapped allocator to forward requests to. Must remain valid for the lifetime of this object.

◆ TrackingAllocator() [4/7]

template<typename MetricsType >
constexpr pw::allocator::TrackingAllocator< MetricsType >::TrackingAllocator ( metric::Token  token,
const Capabilities &  capabilities,
metric::GroupList &  groups 
)
inlineconstexprnoexcept

Constructs a tracking allocator without setting its wrapped allocator and registers its metric_group() in groups (for example pw::metric::global_groups or parent_group.children()).

Init() must be called with the wrapped allocator before any allocation methods are invoked. Can be used with PW_CONSTINIT inside a composite struct containing groups regardless of which metrics MetricsType enables.

Parameters
[in]tokenTokenized name of this allocator's metric group.
[in]capabilitiesCapabilities exposed by this allocator.
[in,out]groupsMetric group list to register metric_group() in.
Precondition
groups must already be initialized, and access to groups during construction and destruction must be externally synchronized.

◆ TrackingAllocator() [5/7]

template<typename MetricsType >
constexpr pw::allocator::TrackingAllocator< MetricsType >::TrackingAllocator ( metric::Token  token,
Allocator &  allocator,
const Capabilities &  capabilities,
metric::GroupList &  groups 
)
inlineconstexpr

Constructs a tracking allocator wrapping allocator with explicit capabilities and registers its metric_group() in groups.

Does not read allocator.capabilities(), so it can be used with PW_CONSTINIT inside a composite struct containing groups when wrapping a separate static allocator and MetricsType only enables counter metrics.

Parameters
[in]tokenTokenized name of this allocator's metric group.
[in,out]allocatorWrapped allocator to forward requests to. Must remain valid for the lifetime of this object.
[in]capabilitiesCapabilities exposed by this allocator.
[in,out]groupsMetric group list to register metric_group() in.
Precondition
groups must already be initialized, and access to groups during construction and destruction must be externally synchronized.

◆ TrackingAllocator() [6/7]

template<typename MetricsType >
constexpr pw::allocator::TrackingAllocator< MetricsType >::TrackingAllocator ( metric::Token  token,
Allocator &  allocator,
metric::GroupList &  groups 
)
inlineconstexpr

Constructs a tracking allocator wrapping allocator and registers its metric_group() in groups (for example pw::metric::global_groups or parent_group.children()).

Parameters
[in]tokenTokenized name of this allocator's metric group.
[in,out]allocatorWrapped allocator to forward requests to. Must remain valid for the lifetime of this object.
[in,out]groupsMetric group list to register metric_group() in.
Precondition
groups must already be initialized (pw::metric::global_groups is PW_CONSTINIT and safe during dynamic static initialization; avoid passing children() of a dynamically initialized global Group in another translation unit), and access to groups during construction and destruction must be externally synchronized.

◆ TrackingAllocator() [7/7]

template<typename MetricsType >
template<typename OtherMetrics >
constexpr pw::allocator::TrackingAllocator< MetricsType >::TrackingAllocator ( metric::Token  token,
TrackingAllocator< OtherMetrics > &  parent,
const AddTrackingAllocatorAsChild &   
)
inlineconstexpr

Constructs a tracking allocator wrapping parent and adds its metric_group() as a child of parent.metric_group().

Parameters
[in]tokenTokenized name of this allocator's metric group.
[in,out]parentParent tracking allocator to wrap and register under. Must remain valid for the lifetime of this object.

Member Function Documentation

◆ UpdateDeferred()

template<typename MetricsType >
void pw::allocator::TrackingAllocator< MetricsType >::UpdateDeferred ( )
inline

Requests to update out-of-band metrics, if any.

See also NoMetrics::UpdateDeferred.


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