Rhino C++ API  7.21
Public Member Functions | Static Public Member Functions | Friends | List of all members
ON_FixedSizePool Class Reference

#include <opennurbs_fsp.h>

Inheritance diagram for ON_FixedSizePool:
ON_Internal_FontGlyphPool ON_MeshXPointPool ON_SimpleFixedSizePool< T >

Public Member Functions

 ON_FixedSizePool ()
 
 ~ON_FixedSizePool ()
 
size_t ActiveElementCount () const
 
void * AllocateDirtyElement ()
 
void * AllocateElement ()
 
bool Create (size_t sizeof_element)
 
bool Create (size_t sizeof_element, size_t element_count_estimate, size_t block_element_capacity)
 
bool CreateForExperts (size_t sizeof_element, size_t maximum_element_count_estimate, size_t minimum_block2_element_capacity)
 
void Destroy ()
 
void * Element (size_t element_index) const
 
void * ElementFromId (size_t id_offset, unsigned int id) const
 
bool ElementIdIsIncreasing (size_t id_offset) const
 
size_t ElementIndex (const void *element_pointer) const
 
bool InPool (const void *pointer) const
 
bool IsValid () const
 Primarily used for debugging. More...
 
unsigned int MaximumElementId (size_t id_offset) const
 
unsigned int ResetElementId (size_t id_offset, unsigned int initial_id)
 
void ReturnAll ()
 
void ReturnElement (void *p)
 
size_t SizeOfActiveElements () const
 
size_t SizeofElement () const
 
size_t SizeOfPool () const
 
size_t SizeOfUnusedElements () const
 
void * ThreadSafeAllocateDirtyElement ()
 
void * ThreadSafeAllocateElement ()
 
void ThreadSafeReturnElement (void *p)
 
size_t TotalElementCount () const
 

Static Public Member Functions

static size_t DefaultElementCapacityFromSizeOfElement (size_t sizeof_element)
 

Friends

class ON_FixedSizePoolIterator
 
class ON_SleepLockGuard
 

Constructor & Destructor Documentation

◆ ON_FixedSizePool()

ON_FixedSizePool::ON_FixedSizePool ( )

◆ ~ON_FixedSizePool()

ON_FixedSizePool::~ON_FixedSizePool ( )

Member Function Documentation

◆ ActiveElementCount()

size_t ON_FixedSizePool::ActiveElementCount ( ) const

Returns: Number of active elements. (Elements that have been returned are not active.)

◆ AllocateDirtyElement()

void* ON_FixedSizePool::AllocateDirtyElement ( )

Returns: A pointer to sizeof_element bytes. The values in the returned block are undefined. Remarks: If multiple threads are using this pool, then use ThreadSafeAllocateDirtyElement().

◆ AllocateElement()

void* ON_FixedSizePool::AllocateElement ( )

Returns: A pointer to sizeof_element bytes. The memory is zeroed. Remarks: If multiple threads are using this pool, then use ThreadSafeAllocateElement().

◆ Create() [1/2]

bool ON_FixedSizePool::Create ( size_t  sizeof_element)

Description: Create a fixed size memory pool. Parameters: sizeof_element - [in] number of bytes in each element. This parameter must be greater than zero. In general, use sizeof(element type). If you pass a "raw" number as sizeof_element, then be certain that it is the right size to insure the fields in your elements will be properly aligned. Remarks: You must call Create() on an unused ON_FixedSizePool or call Destroy() before calling create. Returns: True if successful and the pool can be used. See Also CreateForExperts().

◆ Create() [2/2]

bool ON_FixedSizePool::Create ( size_t  sizeof_element,
size_t  element_count_estimate,
size_t  block_element_capacity 
)

Description: Create a fixed size memory pool. If you have a decent estimate of how many elements you need, CreateForExperts() is a typically a better choice. Otherwise, Create(sizeof_element) is typically the best option.

Parameters: sizeof_element - [in] number of bytes in each element. This parameter must be greater than zero. In general, use sizeof(element type). If you pass a "raw" number as sizeof_element, then be certain that it is the right size to insure the fields in your elements will be properly aligned. element_count_estimate - [in] (0 = good default) If you know how many elements you will need, pass that number here. It is better to slightly overestimate than to slightly underestimate. If you do not have a good estimate, then use zero. block_element_capacity - [in] (0 = good default) If block_element_capacity is zero, Create() will calculate a block size that is efficent for most applications. If you are an expert user and want to specify the number of elements per block, then pass the number of elements per block here. When block_element_capacity > 0 and element_count_estimate > 0, the first block will have a capacity of at least element_count_estimate; in this case do not ask for extraordinarly large amounts of contiguous heap.

Remarks: You must call Create() on an unused ON_FixedSizePool or call Destroy() before calling create. Returns: True if successful and the pool can be used.

◆ CreateForExperts()

bool ON_FixedSizePool::CreateForExperts ( size_t  sizeof_element,
size_t  maximum_element_count_estimate,
size_t  minimum_block2_element_capacity 
)

Description: Create a fixed size memory pool. Parameters: sizeof_element - [in] number of bytes in each element. This parameter must be greater than zero. In general, use sizeof(element type). If you pass a "raw" number as sizeof_element, then be certain that it is the right size to insure the fields in your elements will be properly aligned.

maximum_element_count_estimate - [in] (0 = good default) If you have a tight upper bound on the number of elements you need from this fixed size pool, call Create(sizeof_element) instead.

If the description of this parameter is confusing to you, call Create(sizeof_element) instead.

If you have a tight upper bound on how many elements you will need, pass that number here. When maximum_element_count_estimate > 0, the initial memory blocks in the fixed size pool will be sized to efficiently deliver maximum_element_count_estimate elements. The fixed block pool can become inefficient when maximum_element_count_estimate is a gross overestimate or a slight underestimate of the actual number of elements that get allocated.

minimum_block2_element_capacity - [in] (0 = good default) If the description below is confusing, pass 0. If maximum_element_count_estimate = 0, this parameter is ignored. If maximum_element_count_estimate > 0 and you have an excellent choice for a lower bound on the number of elements per block for unexpected allocations of more than maximum_element_count_estimate elements, then pass that value for minimum_block2_element_capacity.

Remarks: You must call Create() or CreateEx() on an unused ON_FixedSizePool or call Destroy() before calling create. Returns: True if successful and the pool can be used.

◆ DefaultElementCapacityFromSizeOfElement()

static size_t ON_FixedSizePool::DefaultElementCapacityFromSizeOfElement ( size_t  sizeof_element)
static

◆ Destroy()

void ON_FixedSizePool::Destroy ( )

Description: Destroy the pool and free all the heap. The pool cannot be used again until Create() is called.

◆ Element()

void* ON_FixedSizePool::Element ( size_t  element_index) const

Description: Get the i-th elment in the fixed size pool. Parameters: element_index - [in] Returns: A pointer to the element with the specified index.
The first element has element_index = 0 and is the element returned by the first call to AllocateElement(). The last element has element_index = ElementCount()-1. If element_index is out of range, nullptr is returned. Remarks: It is faster to use ON_FixedSizePoolIterator.FirstElement() and ON_FixedSizePoolIterator.NextElement() to iterate through the entire list of elements. This function is relatively efficient when there are a few large blocks in the pool or element_index is small compared to the number of elements in the first few blocks.

If ReturnElement() is not used or no AllocateElement() calls are made after any use of ReturnElement(), then the i-th element is the one returned by the (i+1)-th call to AllocateElement()

◆ ElementFromId()

void* ON_FixedSizePool::ElementFromId ( size_t  id_offset,
unsigned int  id 
) const

Description: If you are certain that all elements in the pool (active and returned) have an unsigned 32-bit id that is unique and increasing, then you may use this function to find them. Parameters: id_offset - [in] offset into the element where the id is stored. id - [in] id to search for

◆ ElementIdIsIncreasing()

bool ON_FixedSizePool::ElementIdIsIncreasing ( size_t  id_offset) const

◆ ElementIndex()

size_t ON_FixedSizePool::ElementIndex ( const void *  element_pointer) const

Description: Get the fixed size pool index of an element. Parameters: element_pointer - [in] Returns: An index >= 0 and < ON_MAX_SIZE_T if the element_pointer points to an element managed by the this fixed size pool. ON_MAX_SIZE_T otherwise. Remarks: It is faster to use ON_FixedSizePoolIterator.FirstElement() and ON_FixedSizePoolIterator.NextElement() to iterate through the entire list of elements. This function is relatively efficient when there are a few large blocks in the pool or element_pointer is an element in the first few blocks.

If ReturnElement() is not used or no AllocateElement() calls are made after any use of ReturnElement(), then the i-th element is the one returned by the (i+1)-th call to AllocateElement().

◆ InPool()

bool ON_FixedSizePool::InPool ( const void *  pointer) const

Parameters: p - [in] pointer to test Returns: True if p points to memory in this pool.

◆ IsValid()

bool ON_FixedSizePool::IsValid ( ) const

Primarily used for debugging.

◆ MaximumElementId()

unsigned int ON_FixedSizePool::MaximumElementId ( size_t  id_offset) const

Description: If you are certain that all elements in the pool (active and returned) have an unsigned 32-bit id that is unique and increasing, then you may use this function to find the maximum assigned id. Parameters: id_offset - [in] offset into the element where the id is stored. Returns: maximum id in all elements (active and returned).

◆ ResetElementId()

unsigned int ON_FixedSizePool::ResetElementId ( size_t  id_offset,
unsigned int  initial_id 
)

Returns: If successful, (1 + maximum assigned id value) is returned. Otherwise 0 is returned.

◆ ReturnAll()

void ON_FixedSizePool::ReturnAll ( )

Description: Return all allocated elements to the pool. No heap is freed and the pool remains initialized and ready for AllocateElement() to be called.

◆ ReturnElement()

void ON_FixedSizePool::ReturnElement ( void *  p)

Description: Return an element to the pool. Parameters: p - [in] A pointer returned by AllocateElement(). It is critical that p be from this pool and that you return a pointer no more than one time. Remarks: If multiple threads are using this pool, then use ThreadSafeReturnElement().

If you find the following remarks confusing, but you really want to use ReturnElement(), then here are some simple guidelines. 1) SizeofElement() must be >= 16 2) SizeofElement() must be a multiple of 8. 3) Do not use FirstElement() and NextElement() to iterate through the pool.

If 1 to 3 don't work for you, then you need to understand the following information before using ReturnElement().

ON_FixedMemoryPool uses the first sizeof(void*) bytes of the returned element for bookkeeping purposes. Therefore, if you are going to use ReturnElement(), then SizeofElement() must be at least sizeof(void*). If you are using a platform that requires pointers to be aligned on sizeof(void*) boundaries, then SizeofElement() must be a multiple of sizeof(void*). If you are going to use ReturnElement() and then use FirstElement() and NextElement() to iterate through the list of elements, then you need to set a value in the returned element to indicate that it needs to be skipped during the iteration. This value cannot be located in the fist sizeof(void*) bytes of the element. If the element is a class with a vtable, you cannot call a virtual function on a returned element because the vtable pointer is trashed when ReturnElement() modifies the fist sizeof(void*) bytes.

◆ SizeOfActiveElements()

size_t ON_FixedSizePool::SizeOfActiveElements ( ) const

Description: Tool for debugging pool use when tuning block size and block capacity. Returns: Operating system heap memory (in bytes) that are used by active pool elements. Remarks: SizeOfPool() = SizeOfActiveElements() + SizeOfUnusedElements().

◆ SizeofElement()

size_t ON_FixedSizePool::SizeofElement ( ) const

Returns: Size of the elements in this pool.

◆ SizeOfPool()

size_t ON_FixedSizePool::SizeOfPool ( ) const

Description: Tool for debugging pool use when tuning block size and block capacity. Returns: Total operating system heap memory (in bytes) used by this ON_FixedSizePool. Remarks: SizeOfPool() = SizeOfAllocatedElements() + SizeOfUnusedElements().

◆ SizeOfUnusedElements()

size_t ON_FixedSizePool::SizeOfUnusedElements ( ) const

Description: Tool for debugging pool use when tuning block size and block capacity. Returns: Operating system heap memory (in bytes) that has been reserved but is not currently used by active elements. Remarks: SizeOfPool() = SizeOfActiveElements() + SizeOfUnusedElements().

◆ ThreadSafeAllocateDirtyElement()

void* ON_FixedSizePool::ThreadSafeAllocateDirtyElement ( )

Description: Thread safe version of AllocateDirtyElement(). Returns: A pointer to sizeof_element bytes. The values in the returned block are undefined.

◆ ThreadSafeAllocateElement()

void* ON_FixedSizePool::ThreadSafeAllocateElement ( )

Description: Thread safe version of AllocateElement(). Returns: A pointer to sizeof_element bytes. The memory is zeroed.

◆ ThreadSafeReturnElement()

void ON_FixedSizePool::ThreadSafeReturnElement ( void *  p)

Description: Thread safe version of ReturnElement().

◆ TotalElementCount()

size_t ON_FixedSizePool::TotalElementCount ( ) const

Returns: Total number of elements = number of active elements + number of returned elements.

Friends And Related Function Documentation

◆ ON_FixedSizePoolIterator

friend class ON_FixedSizePoolIterator
friend

◆ ON_SleepLockGuard

friend class ON_SleepLockGuard
friend

Used by The ThreadSafe...() functions and for expert users to use when managing memory controlled by this pool. Best to ingnore this unless you have a very clear idea of what you are doing, why you are doing it, and when you are doing it. Otherwise, you'll find yourself waiting forever on a nested access request.