#include <opennurbs_fsp.h>
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 efficient 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 |
◆ 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 element 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 |
◆ ON_SleepLockGuard
|
friend |
Used by The ThreadSafe...() functions and for expert users to use when managing memory controlled by this pool. Best to ignore 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.
