pw::allocator::test::TestHarness Class Reference

#include <test_harness.h>

Classes
struct	Allocation
	Associates a pointer to memory with the Layout used to allocate it. More...

Public Member Functions
	TestHarness (Allocator &allocator)
size_t	num_allocations () const
size_t	allocated () const
void	set_allocator (Allocator *allocator)
void	set_prng_seed (uint64_t seed)
void	set_available (size_t available)
void	GenerateRequests (size_t max_size, size_t num_requests)
void	GenerateRequest (size_t max_size)
void	HandleRequests (const Vector< Request > &requests)
bool	HandleRequest (const Request &request)
void	Reset ()
	Deallocates any pointers stored in the vector of allocated pointers.

Private Member Functions
virtual void	BeforeAllocate (const Layout &)

Detailed Description

Associates an Allocator with a list to store allocated pointers.

This class facilitates performing allocations from generated Requests, enabling the creation of performance, stress, and fuzz tests for various allocators.

This class does NOT implement TestHarness::Init. It must be extended further with a method that provides an initialized allocator.

For example, one can create a fuzzer for MyAllocator that verifies it never crashes by adding the following class, function, and macro:

void MyAllocatorNeverCrashes(const Vector<Request>& requests) {
  static MyAllocator allocator;
  static TestHarness fuzzer(allocator);
  fuzzer.HandleRequests(requests);
}
 
FUZZ_TEST(MyAllocator, MyAllocatorNeverCrashes)
  .WithDomains(DefaultArbitraryRequests());

Member Function Documentation

BeforeAllocate()

virtual void pw::allocator::test::TestHarness::BeforeAllocate ( const Layout &  )

inlineprivatevirtual

Derived classes may add callbacks that are invoked before and after each de/re/allocation to record additional data about the allocator.

GenerateRequest()

void pw::allocator::test::TestHarness::GenerateRequest

(

size_t

max_size

)

Generate and handle an allocation requests.

This method will use the given PRNG to generate an allocation request and pass it to HandleRequest. Callers MUST call Reset when no more requests remain to be generated.

GenerateRequests()

void pw::allocator::test::TestHarness::GenerateRequests	(	size_t	max_size,
		size_t	num_requests
	)

Generates and handles a sequence of allocation requests.

This method will use the given PRNG to generate num_requests allocation requests and pass each in turn to HandleRequest. It will call Reset before returning.

HandleRequest()

bool pw::allocator::test::TestHarness::HandleRequest

(

const Request &

request

)

Handles an allocator request.

This method is stateful, and modifies the vector of allocated pointers. It will call Init if it has not yet been called.

If the request is an allocation request:

• If the vector of previous allocations is full, ignores the request.
• Otherwise, allocates memory and stores the pointer in the vector.

If the request is a deallocation request:

• If the vector of previous allocations is empty, ignores the request.
• Otherwise, removes a pointer from the vector and deallocates it.

If the request is a reallocation request:

• If the vector of previous allocations is empty, reallocates a nullptr.
• Otherwise, removes a pointer from the vector and reallocates it.

Returns whether the request was handled. This is different from whether the request succeeded, e.g. a DeallocationRequest cannot be handled when there are no current allocations and will return false. By contrast, an AllocationRequest may be handled, but fail due to insufficient memory, and will return true.

HandleRequests()

void pw::allocator::test::TestHarness::HandleRequests

(

const Vector< Request > &

requests

)

Handles a sequence of allocation requests.

This method is useful for processing externally generated requests, e.g. from FuzzTest. It will call Reset before returning.

---

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

• pw_allocator/public/pw_allocator/test_harness.h