ON_SimpleFixedSizePool< T > Class Template Reference

#include <opennurbs_fsp.h>

Inheritance diagram for ON_SimpleFixedSizePool< T >:

Public Member Functions
	ON_SimpleFixedSizePool ()
	construction //////////////////////////////////////////////////////// More...
	~ON_SimpleFixedSizePool ()
size_t	ActiveElementCount () const
T *	AllocateElement ()
bool	Create (size_t element_count_estimate, size_t block_element_count)
	Create a fixed size memory pool. More...
void	Destroy ()
	Destroy the pool and free all the heap. The pool cannot be used again until Create() is called. More...
T *	Element (size_t element_index) const
	Get the i-th elment in the pool. More...
size_t	ElementIndex (T *) const
void	ReturnAll ()
	Return all allocated elements to the pool. No heap is freed and the pool remains initialized and ready for AllocateElement() to be called. More...
void	ReturnElement (T *p)
	Return an element to the pool. More...
size_t	SizeofElement () const
size_t	TotalElementCount () const

Constructor & Destructor Documentation

ON_SimpleFixedSizePool()

template<class T >

ON_SimpleFixedSizePool< T >::ON_SimpleFixedSizePool

(

)

construction ////////////////////////////////////////////////////////

~ON_SimpleFixedSizePool()

template<class T >

ON_SimpleFixedSizePool< T >::~ON_SimpleFixedSizePool

(

)

Member Function Documentation

ActiveElementCount()

template<class T >

size_t ON_SimpleFixedSizePool< T >::ActiveElementCount

(

)

const

Returns

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

AllocateElement()

template<class T >

T * ON_SimpleFixedSizePool< T >::AllocateElement

(

)

Returns

A pointer to sizeof_element bytes. The memory is zeroed.

Create()

template<class T >

bool ON_SimpleFixedSizePool< T >::Create	(	size_t	element_count_estimate,
		size_t	block_element_count
	)

Create a fixed size memory pool.

Parameters

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_count

[in] (0 = good default) If block_element_count 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 blocks, then pass the number of elements per block here. When block_element_count > 0 and element_count_estimate > 0, the first block will be large enough element_count_estimate*sizeof(T) bytes; in this case do not ask for extraordinarly large amounts of contiguous heap.

Returns

True if successful and the pool can be used.

You must call Create() on an unused ON_FixedSizePool or call Destroy() before calling create.

Destroy()

template<class T >

void ON_SimpleFixedSizePool< T >::Destroy

(

)

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

Element()

template<class T >

T * ON_SimpleFixedSizePool< T >::Element

(

size_t

element_index

)

const

Get the i-th elment in the pool.

Parameters

element_index

[in]

Returns

A pointer to the i-th element. The first element has index = 0 and is the element returned by the first call to AllocateElement(). The last element has index = ElementCount()-1. If i is out of range, null is returned.

It is faster to use FirstElement() and 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 AllocateElement() calls to are made after any use of ReturnElement(), then the i-th element is the one returned by the (i+1)-th call to AllocateElement().

ElementIndex()

template<class T >

size_t ON_SimpleFixedSizePool< T >::ElementIndex

(

T *

element_ptr

)

const

ReturnAll()

template<class T >

void ON_SimpleFixedSizePool< T >::ReturnAll

(

)

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

ReturnElement()

template<class T >

void ON_SimpleFixedSizePool< T >::ReturnElement

(

T *

p

)

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.

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.

SizeofElement()

template<class T >

size_t ON_SimpleFixedSizePool< T >::SizeofElement

(

)

const

Returns

Size of the elements in this pool.

TotalElementCount()

template<class T >

size_t ON_SimpleFixedSizePool< T >::TotalElementCount

(

)

const

Returns

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