Pigweed
 
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
pw::allocator::BasicBlock< Derived > Class Template Reference

#include <basic.h>

Inheritance diagram for pw::allocator::BasicBlock< Derived >:
pw::allocator::internal::BasicBase

Public Member Functions

 BasicBlock (const BasicBlock &other)=delete
 
BasicBlock & operator= (const BasicBlock &other)=delete
 
constexpr std::byte * UsableSpace ()
 
constexpr const std::byte * UsableSpace () const
 
constexpr std::byte * UsableSpaceUnchecked ()
 
constexpr const std::byte * UsableSpaceUnchecked () const
 
constexpr size_t OuterSize () const
 
constexpr size_t InnerSize () const
 
constexpr size_t InnerSizeUnchecked () const
 
constexpr bool IsValid () const
 
constexpr bool CheckInvariants () const
 Like IsValid, but crashes if invalid.
 

Static Public Member Functions

static constexpr Result< Derived * > Init (ByteSpan region)
 Creates the first block for a given memory region.
 
template<typename Ptr >
static constexpr internal::copy_const_ptr_t< Ptr, Derived * > FromUsableSpace (Ptr usable_space)
 
static constexpr size_t OuterSizeFromInnerSize (size_t inner_size)
 
static constexpr size_t InnerSizeFromOuterSize (size_t outer_size)
 

Static Public Attributes

static constexpr size_t kAlignment = Derived::DefaultAlignment()
 
static constexpr size_t kBlockOverhead
 
static constexpr size_t kMinOuterSize
 

Protected Member Functions

constexpr bool DoCheckInvariants (bool strict) const
 

Detailed Description

template<typename Derived>
class pw::allocator::BasicBlock< Derived >

Base mix-in for block implementations.

This CRTP-style type can be combined with block mix-in types. Block mix-ins are stateless and trivially constructible. Mix-ins require the derived class to implement methods to access and modify state, such has how to return a block's size or a pointer to its usable memory.

The mix-ins also follow the NVI pattern. This allows mix-ins to layer behavior for a particular method. For example, the implementation of AllocFirst in AlignableBlock handles allocation with larger than default alignment requirements, and delegates to AllocatableBlock for other requests. The derived type provided by the concrete block implementation can implement the public method that delegates to the correct mix-in. Overridable methods are named Do....

These mix-ins guarantee a number of invariants hold at the beginning and end of each regular public API call. Each mix-in can enforce invariants by overriding DoCheckInvariants. The concrete block implementation should override the same method by calling each of the relevant mix-in methods. Calling a public API method within an implementation of DoCheckInvariants will lead to infinite recursion. To avoid this, mix-ins provide and/or require versions of methods named ...Unchecked that skip checking invariants. These should only be used within the context of DoCheckInvariants or other ...Unchecked methods.

This mix-in requires its derived type provide the following symbols:

  • static constexpr size_t DefaultAlignment()
    • Returns the alignment of the block type. Must be a power of two.
  • static constexpr size_t BlockOverhead()
    • Returns the size of the metadata at the start of a block, before its usable space.
  • static constexpr size_t MaxAddressableSize()
    • Size of the largest region that can be addressed by a block.
  • static constexpr size_t MinInnerSize()
    • Returns the minimum inner size of a block. Can be 1 unless the usable space is used to track blocks when they are free.
  • static Derived* AsBlock(BytesSpan)
    • Instantiates and returns a block for the given region of memory.
  • size_t OuterSizeUnchecked() const
    • Returns the size of the block. Must be multiple of kAlignment.

Member Function Documentation

◆ DoCheckInvariants()

template<typename Derived >
constexpr bool pw::allocator::BasicBlock< Derived >::DoCheckInvariants ( bool  strict) const
constexprprotected

Checks that the various block conditions that should always be true are indeed true.

Triggers a fatal error if strict is true.

◆ FromUsableSpace()

template<typename Derived >
template<typename Ptr >
constexpr internal::copy_const_ptr_t< Ptr, Derived * > pw::allocator::BasicBlock< Derived >::FromUsableSpace ( Ptr  usable_space)
staticconstexpr
Returns
A pointer to a Block, given a pointer to the start of the usable space inside the block.

This is the inverse of UsableSpace().

Warning
This method does not do any checking; passing a random pointer will return a non-null pointer.

◆ Init()

template<typename Derived >
constexpr Result< Derived * > pw::allocator::BasicBlock< Derived >::Init ( ByteSpan  region)
staticconstexpr

Creates the first block for a given memory region.

Returns
embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: Returns a block representing the region.
* 
*     INVALID_ARGUMENT: The region is null.
* 
*     RESOURCE_EXHAUSTED: The region is too small for a block.
* 
*     OUT_OF_RANGE: The region is larger than `kMaxAddressableSize`.
* 
*

◆ InnerSize()

template<typename Derived >
constexpr size_t pw::allocator::BasicBlock< Derived >::InnerSize
constexpr
Returns
The number of usable bytes inside the block.

◆ InnerSizeFromOuterSize()

template<typename Derived >
constexpr size_t pw::allocator::BasicBlock< Derived >::InnerSizeFromOuterSize ( size_t  outer_size)
staticconstexpr
Returns
The inner size of a block from the corresponding outer size.

◆ IsValid()

template<typename Derived >
constexpr bool pw::allocator::BasicBlock< Derived >::IsValid
constexpr
Returns
whether a block is valid.

◆ OuterSize()

template<typename Derived >
constexpr size_t pw::allocator::BasicBlock< Derived >::OuterSize
constexpr
Returns
The total size of the block in bytes, including the header.

◆ OuterSizeFromInnerSize()

template<typename Derived >
constexpr size_t pw::allocator::BasicBlock< Derived >::OuterSizeFromInnerSize ( size_t  inner_size)
staticconstexpr
Returns
The outer size of a block from the corresponding inner size.

◆ UsableSpace()

template<typename Derived >
constexpr std::byte * pw::allocator::BasicBlock< Derived >::UsableSpace
constexpr
Returns
A pointer to the usable space inside this block.

Member Data Documentation

◆ kBlockOverhead

template<typename Derived >
constexpr size_t pw::allocator::BasicBlock< Derived >::kBlockOverhead
staticconstexpr
Initial value:
=
AlignUp(Derived::BlockOverhead(), kAlignment)
pw::AlignUp
constexpr size_t AlignUp(uintptr_t value, size_t alignment)
Returns the value rounded up to the nearest multiple of alignment.
Definition: alignment.h:52

◆ kMinOuterSize

template<typename Derived >
constexpr size_t pw::allocator::BasicBlock< Derived >::kMinOuterSize
staticconstexpr
Initial value:
=
kBlockOverhead + AlignUp(Derived::MinInnerSize(), kAlignment)
The documentation for this class was generated from the following file: