Oveview

Helpers for metrics, fragmentation, and buffer management.

Classes
class	pw::allocator::WithBuffer< T, kBufferSize, kAlignment >

struct	pw::allocator::AlignedBuffer< kBufferSize, kAlignment >
	Convenience alias for creating aligned byte buffers. More...

struct	pw::allocator::Fragmentation

struct	pw::allocator::NoMetrics

struct	pw::allocator::internal::AllMetrics

class	pw::allocator::internal::Metrics< MetricsType >

Macros
#define	PW_ALLOCATOR_METRICS_FOREACH(fn)

#define	PW_ALLOCATOR_ABSORB_SEMICOLON() static_assert(true)

#define	PW_ALLOCATOR_METRICS_DECLARE(metric_name)

#define	PW_ALLOCATOR_METRICS_INCLUDE(metric_name)

#define	PW_ALLOCATOR_METRICS_ENABLE(metric_name)

Functions
float	pw::allocator::CalculateFragmentation (const Fragmentation &fragmentation)

static constexpr bool	pw::allocator::NoMetrics::has_requested_bytes ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_requested_bytes () const

static constexpr bool	pw::allocator::NoMetrics::requested_bytes_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_peak_requested_bytes ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_peak_requested_bytes () const

static constexpr bool	pw::allocator::NoMetrics::peak_requested_bytes_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_cumulative_requested_bytes ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_cumulative_requested_bytes () const

static constexpr bool	pw::allocator::NoMetrics::cumulative_requested_bytes_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_allocated_bytes ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_allocated_bytes () const

static constexpr bool	pw::allocator::NoMetrics::allocated_bytes_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_peak_allocated_bytes ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_peak_allocated_bytes () const

static constexpr bool	pw::allocator::NoMetrics::peak_allocated_bytes_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_cumulative_allocated_bytes ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_cumulative_allocated_bytes () const

static constexpr bool	pw::allocator::NoMetrics::cumulative_allocated_bytes_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_num_allocations ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_num_allocations () const

static constexpr bool	pw::allocator::NoMetrics::num_allocations_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_num_deallocations ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_num_deallocations () const

static constexpr bool	pw::allocator::NoMetrics::num_deallocations_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_num_resizes ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_num_resizes () const

static constexpr bool	pw::allocator::NoMetrics::num_resizes_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_num_reallocations ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_num_reallocations () const

static constexpr bool	pw::allocator::NoMetrics::num_reallocations_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_num_free_blocks ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_num_free_blocks () const

static constexpr bool	pw::allocator::NoMetrics::num_free_blocks_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_smallest_free_block_size ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_smallest_free_block_size () const

static constexpr bool	pw::allocator::NoMetrics::smallest_free_block_size_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_largest_free_block_size ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_largest_free_block_size () const

static constexpr bool	pw::allocator::NoMetrics::largest_free_block_size_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_num_failures ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_num_failures () const

static constexpr bool	pw::allocator::NoMetrics::num_failures_enabled ()

static constexpr bool	pw::allocator::NoMetrics::has_unfulfilled_bytes ()

::pw::StatusWithSize	pw::allocator::NoMetrics::get_unfulfilled_bytes () const

static constexpr bool	pw::allocator::NoMetrics::unfulfilled_bytes_enabled ()

void	pw::allocator::NoMetrics::UpdateDeferred (Allocator &)

template<typename MetricsType >
constexpr bool	pw::allocator::internal::AnyEnabled ()

template<typename MetricsType >
void	pw::allocator::internal::CopyMetrics (const MetricsType &src, MetricsType &dst)
	Copies the values enabled for a given `MetricsType` from `src` to `dst`.

uint32_t	pw::allocator::internal::ClampU32 (size_t size)
	Helper method for converting `size_t`s to `uint32_t`s.

Macro Definition Documentation

◆ PW_ALLOCATOR_METRICS_DECLARE

#define PW_ALLOCATOR_METRICS_DECLARE ( metric_name )

Value:

  static constexpr bool has_##metric_name() { return false; }     \
  ::pw::StatusWithSize get_##metric_name() const {                \
    return ::pw::StatusWithSize::NotFound();                      \
  }                                                               \
  static constexpr bool metric_name##_enabled() { return false; } \
  PW_ALLOCATOR_ABSORB_SEMICOLON()

Declares the names of metrics used by pw::allocator::Metrics.

Only the names of declared metrics may be passed to PW_ALLOCATOR_METRICS_ENABLE as part of a metrics struct definition.

This macro generates trait types that are used by Metrics to conditionally include metric-related code.

Note: if enabling `peak_allocated_bytes or cumulative_allocated_bytes, allocated_bytes should also be enabled.

◆ PW_ALLOCATOR_METRICS_ENABLE

#define PW_ALLOCATOR_METRICS_ENABLE ( metric_name )

Value:

static constexpr bool metric_name##_enabled() { return true; } \

PW_ALLOCATOR_METRICS_INCLUDE(metric_name)

Enables a metric for in a metrics struct.

The pw::allocator::TrackingAllocator template takes a struct that enables zero or more of the metrics enumerated by PW_ALLOCATOR_METRICS_DECLARE`.

This struct may be one of AllMetrics or NoMetrics, or may be a custom struct that selects a subset of metrics.

A metric that is enabled is expected to be updated automatically by using a tracking allocator's API.

Example:

struct MyMetrics {
  PW_ALLOCATOR_METRICS_ENABLE(allocated_bytes);
  PW_ALLOCATOR_METRICS_ENABLE(peak_allocated_bytes);
  PW_ALLOCATOR_METRICS_INCLUDE(num_free_blocks);
 
  void UpdateDeferred(Allocator& allocator);
};

◆ PW_ALLOCATOR_METRICS_FOREACH

#define PW_ALLOCATOR_METRICS_FOREACH ( fn )

Value:

  fn(requested_bytes);                   \
  fn(peak_requested_bytes);              \
  fn(cumulative_requested_bytes);        \
  fn(allocated_bytes);                   \
  fn(peak_allocated_bytes);              \
  fn(cumulative_allocated_bytes);        \
  fn(num_allocations);                   \
  fn(num_deallocations);                 \
  fn(num_resizes);                       \
  fn(num_reallocations);                 \
  fn(num_free_blocks);                   \
  fn(smallest_free_block_size);          \
  fn(largest_free_block_size);           \
  fn(num_failures);                      \
  fn(unfulfilled_bytes)

Applies the given macro to each metric.

This macro helps ensure consistency between definitions that involve every metric.

The recognized pw_allocator metrics are:

Metrics to track the current, peak, and cumulative number of bytes requested to be allocated, respectively.
- requested_bytes
- peak_requested_bytes
- cumulative_requested_bytes
Metrics to track the current, peak, and cumulative number of bytes actually allocated, respectively.
- allocated_bytes
- peak_allocated_bytes
- cumulative_allocated_bytes
Metrics to track the number of successful calls to each interface method.
- num_allocations
- num_deallocations
- num_resizes
- num_reallocations
Metrics to track block-related numbers, including the number of free blocks, as well as the sizes of the smallest and largest blocks.
- num_free_blocks
- smallest_free_block_size
- largest_free_block_size
Metrics to tracks the number of interface calls that failed, and the number of bytes requested in those calls.
- num_failures
- unfulfilled_bytes

◆ PW_ALLOCATOR_METRICS_INCLUDE

#define PW_ALLOCATOR_METRICS_INCLUDE ( metric_name )

Value:

  static_assert(!::pw::allocator::NoMetrics::has_##metric_name()); \
  static constexpr bool has_##metric_name() { return true; }       \
  inline ::pw::StatusWithSize get_##metric_name() const {          \
    return ::pw::StatusWithSize(metric_name.value());              \
  }                                                                \
  PW_METRIC(metric_name, #metric_name, 0U)

Includes a metric in a metrics struct.

The pw::allocator::TrackingAllocator template takes a struct that includes zero or more of the metrics enumerated by PW_ALLOCATOR_METRICS_DECLARE`.

This struct may be one of AllMetrics or NoMetrics, or may be a custom struct that selects a subset of metrics.

A metric that is only included, and not enabled, is expected to only be updated when UpdatedDeferred is invoked.

Function Documentation

◆ AnyEnabled()

template<typename MetricsType >

constexpr bool pw::allocator::internal::AnyEnabled ( )

constexpr

Returns whether any metric is enabled. If not, metric collection can be skipped.

◆ CalculateFragmentation()

float pw::allocator::CalculateFragmentation ( const Fragmentation & fragmentation )

Perform the final steps of calculating the fragmentation metric.

This step includes manipulating floating point numbers, and as such it may be desirable to avoid performing this step on device.

◆ UpdateDeferred()

void pw::allocator::NoMetrics::UpdateDeferred ( Allocator & )

inline

Updates metrics by querying an allocator directly.

Metrics are typically updated by an allocator when the pw::Allocator API is invoked. In some cases, there may be metrics that cannot be determined at the interface or are too expensive to do so, e.g. determining the smallest free block. This method provides a way for metrics structs to request these values on-demand.

For this empty base struct, this is simply a no-op.

Oveview

Classes

Macros

Functions

Macro Definition Documentation

◆ PW_ALLOCATOR_METRICS_DECLARE

◆ PW_ALLOCATOR_METRICS_ENABLE

◆ PW_ALLOCATOR_METRICS_FOREACH

◆ PW_ALLOCATOR_METRICS_INCLUDE

Function Documentation

◆ AnyEnabled()

◆ CalculateFragmentation()

◆ UpdateDeferred()