Overview

Forwarding allocator for injecting failures. Forwards calls to a real allocator implementation, or artificially fails if requested.

Note: Allocate, Resize and Reallocate are all fallible methods that may fail at any time, and can therefore be enabled or disabled freely. All others should only be configured during initial configuration. Some allocators check whether these optional methods are implemented during construction and assume they are callable thereafter. Disabling one of these methods later may lead to undefined behavior.

Warning: FaultInjectingAllocator is NOT thread safe, even if used with SynchronizedAllocator.

Inheritance diagram for pw::allocator::test::FaultInjectingAllocator:

Public Member Functions
constexpr	FaultInjectingAllocator (const Capabilities &capabilities) noexcept

constexpr	FaultInjectingAllocator (Allocator &allocator) noexcept

constexpr bool	can_allocate () const

constexpr bool	can_resize () const

constexpr bool	can_reallocate () const

constexpr bool	can_get_capacity () const

constexpr bool	can_get_allocated () const

constexpr bool	can_measure_fragmentation () const

constexpr bool	can_get_requested_layout () const

constexpr bool	can_get_usable_layout () const

constexpr bool	can_get_allocated_layout () const

constexpr bool	can_recognize () const

void	EnableAllocate ()

void	EnableResize ()

void	EnableReallocate ()

void	EnableGetCapacity ()

void	EnableGetAllocated ()

void	EnableMeasureFragmentation ()

void	EnableGetRequestedLayout ()

void	EnableGetUsableLayout ()

void	EnableGetAllocatedLayout ()

void	EnableRecognizes ()

void	DisableAllocate ()

void	DisableResize ()

void	DisableReallocate ()

void	DisableGetCapacity ()

void	DisableGetAllocated ()

void	DisableMeasureFragmentation ()

void	DisableGetRequestedLayout ()

void	DisableGetUsableLayout ()

void	DisableGetAllocatedLayout ()

void	DisableRecognizes ()

void	EnableAll ()
	Forward all calls to the allocator.

void	DisableAll ()
	Return errors for all calls without forwarding to the allocator.

constexpr pw::Allocator &	allocator ()

constexpr const pw::Allocator &	allocator () const

constexpr void	Init (pw::Allocator &allocator)

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)

size_t	GetAllocated () const

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.

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

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
void *	DoAllocate (Layout layout) override

void	DoDeallocate (void *ptr) override

bool	DoResize (void *ptr, size_t new_size) override

void *	DoReallocate (void *ptr, Layout new_layout) override

size_t	DoGetAllocated () 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::ForwardingAllocator
constexpr	ForwardingAllocator (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< 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 size_t	DoGetAllocated () const

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

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, const void *) 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

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>

Member Function Documentation

◆ DoAllocate()

void * pw::allocator::test::FaultInjectingAllocator::DoAllocate ( Layout layout )

inlineoverrideprotectedvirtual

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

Implements pw::Allocator.

Reimplemented in pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType_ >.

◆ DoDeallocate()

void pw::allocator::test::FaultInjectingAllocator::DoDeallocate ( void * ptr )

inlineoverrideprotectedvirtual

Releases a previously-allocated block of memory.

The given pointer must have been previously provided by this memory resource; otherwise the behavior is undefined.

Parameters

[in] ptr Pointer to previously-allocated memory.

Implements pw::Deallocator.

Reimplemented in pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType_ >.

◆ DoGetAllocated()

size_t pw::allocator::test::FaultInjectingAllocator::DoGetAllocated ( ) const

inlineoverrideprotectedvirtual

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.

Reimplemented from pw::Allocator.

◆ DoGetInfo()

Result< Layout > pw::allocator::test::FaultInjectingAllocator::DoGetInfo	(	InfoType	info_type,
		const void *	ptr
	)		const

inlineoverrideprotectedvirtual

Returns deallocator-specific information about allocations.

Deallocators may support any number of InfoTypes. See that type for what each supported type returns. For unsupported types, this method returns UNIMPLEMENTED.

Reimplemented from pw::Deallocator.

◆ DoMeasureFragmentation()

std::optional< Fragmentation > pw::allocator::test::FaultInjectingAllocator::DoMeasureFragmentation ( ) const

inlineoverrideprotectedvirtual

Returns fragmentation information for the allocator's memory region.

Reimplemented from pw::Allocator.

Reimplemented in pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType_ >.

◆ DoReallocate()

void * pw::allocator::test::FaultInjectingAllocator::DoReallocate	(	void *	ptr,
		Layout	new_layout
	)

inlineoverrideprotectedvirtual

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]	ptr	Pointer to previously-allocated memory.
[in]	new_layout	Describes the memory to be allocated.

Reimplemented from pw::Allocator.

◆ DoResize()

bool pw::allocator::test::FaultInjectingAllocator::DoResize	(	void *	ptr,
		size_t	new_size
	)

inlineoverrideprotectedvirtual

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]	ptr	Pointer to previously-allocated memory.
[in]	new_size	Requested new size for the memory allocation.

Reimplemented from pw::Allocator.

Reimplemented in pw::allocator::test::AllocatorForTest< kBufferSize, BlockType_, MetricsType_ >.

◆ Init()

constexpr void pw::allocator::ForwardingAllocator::Init ( pw::Allocator & allocator )

inlineconstexpr

Sets the allocator being wrapped.

It is an error to call this method if an allocator was provided to the constructor.

The allocator must remain valid for the lifetime of this object.

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

pw_allocator/public/pw_allocator/fault_injecting_allocator.h

Overview

Public Member Functions

Protected Member Functions

Additional Inherited Members

Member Function Documentation

◆ DoAllocate()

◆ DoDeallocate()

◆ DoGetAllocated()

◆ DoGetInfo()

◆ DoMeasureFragmentation()

◆ DoReallocate()

◆ DoResize()

◆ Init()