YAKL Pool allocator class. More...

#include <YAKL_Gator.h>

Classes
struct	WaitEntry

Public Member Functions
	Gator ()
	Please use the init() function to specify parameters, not the constructor. More...

	Gator (const Gator &)=delete
	A Gator object may be moved but not copied. More...

	Gator (Gator &&)
	A Gator object may be moved but not copied. More...

	~Gator ()
	All pools are automatically finalized when a Gator object is destroyed. More...

void *	allocate (size_t bytes, char const *label="")
	Allocate the requested number of bytes using the requested label, and return the pointer to allocated space. More...

void	finalize ()
	Finalize the pool allocator, deallocate all individual pools. More...

void	free (void ptr, char const label="")
	Free the passed pointer, and return the pointer to allocated space. More...

void	free_completed_waiting_entries ()
	Check all deallcation entries that are waiting on stream events to see if those events have completed. If the events are completed, then free the entry from the pool. More...

void	free_with_event_dependencies (void ptr, std::vector< Event > events_in, char const label="")
	Free the passed pointer, and return the pointer to allocated space. More...

size_t	get_bytes_currently_allocated () const
	Get the current number of bytes that have been allocated in the pools (this is actual allocation, not pool capacity) More...

size_t	get_high_water_mark () const
	Get the current memory high water mark in bytes for all allocations passing through the pool. More...

size_t	get_num_allocs () const
	Get the total number of allocations in all of the pools put together. More...

int	get_num_pools () const
	Get the current number of pools that have been allocated. More...

size_t	get_pool_capacity () const
	Get the total capacity of all of the pools put together. More...

double	get_pool_high_water_space_efficiency () const
	Get the proportion of total capacity among pools that has been allocated at this largest past memory usage. More...

double	get_pool_space_efficiency () const
	Get the current proportion of total capacity among pools that is actually allocated. More...

void	init (std::function< void (size_t)> mymalloc=[](size_t bytes) -> void { return ::malloc(bytes);}, std::function< void(void )> myfree=[](void ptr) { ::free(ptr);}, std::function< void(void , size_t)> myzero=[](void ptr, size_t bytes) {}, size_t initialSize=1024 1024 1024, size_t growSize=1024 1024 1024, size_t blockSize=16 *sizeof(size_t), std::string pool_name="Gator", std::string error_message_out_of_memory="", std::string error_message_cannot_grow="")
	Initialize the pool. More...

Gator &	operator= (const Gator &)=delete
	A Gator object may be moved but not copied. More...

Gator &	operator= (Gator &&)
	A Gator object may be moved but not copied. More...

void	printAllocsLeft ()
	[USEFUL FOR DEBUGGING] Print all allocations left in this pool object. More...

Protected Attributes
std::mutex	mtx2

std::vector< WaitEntry >	waiting_entries

std::vector< Event >	waiting_events

Detailed Description

YAKL Pool allocator class.

Growable pool allocator for efficient frequent allocations and deallocations. User determines allocation, free, initial pool size, additional pool size, and other pool allocator characteristics upon initiailization.

Once existing pools run out of memory, additional pools are create. Each pool is based on a simple linear search for free slots that is as efficient in memory usage as possible. While search time is linear rather than log in complexity, allocations and frees are typically overlapped with kernel execution.

Gator objects are thread safe for allocate() and free() calls.

Constructor & Destructor Documentation

◆ Gator() [1/3]

yakl::Gator::Gator ( )

inline

Please use the init() function to specify parameters, not the constructor.

◆ Gator() [2/3]

yakl::Gator::Gator ( Gator && )

A Gator object may be moved but not copied.

◆ Gator() [3/3]

yakl::Gator::Gator ( const Gator & )

delete

A Gator object may be moved but not copied.

◆ ~Gator()

yakl::Gator::~Gator ( )

inline

All pools are automatically finalized when a Gator object is destroyed.

Member Function Documentation

◆ allocate()

void* yakl::Gator::allocate	(	size_t	bytes,
		char const *	label = `""`
	)

inline

Allocate the requested number of bytes using the requested label, and return the pointer to allocated space.

The pool allocator will search from beginning to end for a slot large enough to fit this allocation request. This minimizes segmentation at the cost of a linear search time. If the current pool(s) do not contain enough room, a new pool is created.

Attempting to allocate zero bytes will return nullptr. This is a thread safe call.

This always checks to see if entries waiting on stream events are able to be deallocated before allocating.

◆ finalize()

void yakl::Gator::finalize ( )

inline

Finalize the pool allocator, deallocate all individual pools.

◆ free()

void yakl::Gator::free	(	void *	ptr,
		char const *	label = `""`
	)

inline

Free the passed pointer, and return the pointer to allocated space.

Attempting to free a pointer not found in the list of pools will result in a thrown exception

◆ free_completed_waiting_entries()

void yakl::Gator::free_completed_waiting_entries ( )

inline

Check all deallcation entries that are waiting on stream events to see if those events have completed. If the events are completed, then free the entry from the pool.

◆ free_with_event_dependencies()

void yakl::Gator::free_with_event_dependencies	(	void *	ptr,
		std::vector< Event >	events_in,
		char const *	label = `""`
	)

inline

Free the passed pointer, and return the pointer to allocated space.

Attempting to free a pointer not found in the list of pools will result in a thrown exception

◆ get_bytes_currently_allocated()

size_t yakl::Gator::get_bytes_currently_allocated ( ) const

inline

Get the current number of bytes that have been allocated in the pools (this is actual allocation, not pool capacity)

◆ get_high_water_mark()

size_t yakl::Gator::get_high_water_mark ( ) const

inline

Get the current memory high water mark in bytes for all allocations passing through the pool.

◆ get_num_allocs()

size_t yakl::Gator::get_num_allocs ( ) const

inline

Get the total number of allocations in all of the pools put together.

◆ get_num_pools()

int yakl::Gator::get_num_pools ( ) const

inline

Get the current number of pools that have been allocated.

◆ get_pool_capacity()

size_t yakl::Gator::get_pool_capacity ( ) const

inline

Get the total capacity of all of the pools put together.

◆ get_pool_high_water_space_efficiency()

double yakl::Gator::get_pool_high_water_space_efficiency ( ) const

inline

Get the proportion of total capacity among pools that has been allocated at this largest past memory usage.

◆ get_pool_space_efficiency()

double yakl::Gator::get_pool_space_efficiency ( ) const

inline

Get the current proportion of total capacity among pools that is actually allocated.

◆ init()

void yakl::Gator::init	(	std::function< void *(size_t)>	mymalloc = `[] (size_t bytes) -> void * { return ::malloc(bytes); }`,
		std::function< void(void *)>	myfree = `[] (void *ptr) { ::free(ptr); }`,
		std::function< void(void *, size_t)>	myzero = `[] (void *ptr, size_t bytes) {}`,
		size_t	initialSize = `102410241024`,
		size_t	growSize = `102410241024`,
		size_t	blockSize = `16*sizeof(size_t)`,
		std::string	pool_name = `"Gator"`,
		std::string	error_message_out_of_memory = `""`,
		std::string	error_message_cannot_grow = `""`
	)

inline

Initialize the pool.

Parameters

myalloc	The allocator to use when creating the initial and additional pools
myfree	The deallocator to use when destroying all pools upon the Gator object destruction.
myzero	[NOT CURRENTLY USED] The function to use to memset the memory to a value (presumably zero) after initial allocationa and an entry free
initialSize	Size of the initial pool in bytes
growSize	Size of additional pools once the previous pools run out of memory
blockSize	Size of an individual block (the smallest possible entry size. The entry size must increment by this size as well.
pool_name	The label for this pool used in debugging
error_message_out_of_memory	The string printed when a pool allocation fails
error_message_cannot_grow	The string printed when an allocation is requested that overflows initial memory and exceeds the size of additional pools

◆ operator=() [1/2]

Gator& yakl::Gator::operator= ( const Gator & )

delete

A Gator object may be moved but not copied.

◆ operator=() [2/2]

Gator& yakl::Gator::operator= ( Gator && )

A Gator object may be moved but not copied.

◆ printAllocsLeft()

void yakl::Gator::printAllocsLeft ( )

inline

[USEFUL FOR DEBUGGING] Print all allocations left in this pool object.

If you call this regularly in a loop, you can determine if an object fails to be deallocated properly by looking for repeated entries that grow in number each iteration.

Member Data Documentation

◆ mtx2

std::mutex yakl::Gator::mtx2

protected

◆ waiting_entries

std::vector<WaitEntry> yakl::Gator::waiting_entries

protected

◆ waiting_events

std::vector<Event> yakl::Gator::waiting_events

protected

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

YAKL/src/YAKL_Gator.h

Classes

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Gator() [1/3]

◆ Gator() [2/3]

◆ Gator() [3/3]

◆ ~Gator()

Member Function Documentation

◆ allocate()

◆ finalize()

◆ free()

◆ free_completed_waiting_entries()

◆ free_with_event_dependencies()

◆ get_bytes_currently_allocated()

◆ get_high_water_mark()

◆ get_num_allocs()

◆ get_num_pools()

◆ get_pool_capacity()

◆ get_pool_high_water_space_efficiency()

◆ get_pool_space_efficiency()

◆ init()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ printAllocsLeft()

Member Data Documentation

◆ mtx2

◆ waiting_entries

◆ waiting_events