NCollection_IncAllocator Class Reference

#include <NCollection_IncAllocator.hxx>

Inheritance diagram for NCollection_IncAllocator:

Data Structures
struct	IBlock
	Forward list to keep multi-time allocated pointers. On Reset operation objects will be reused. More...

Public Types
enum class	IBlockSizeLevel : unsigned short {   Min = 0 , Small , Medium , Large ,   Max }
	Description ability to next growing size each 5-th new block. More...
typedef void	base_type
	Returns a type descriptor about this object.

Public Member Functions
	NCollection_IncAllocator (const size_t theBlockSize=THE_DEFAULT_BLOCK_SIZE)
	Constructor. Note that this constructor does NOT setup mutex for using allocator concurrently from different threads, see SetThreadSafe() method.
void	SetThreadSafe (const bool theIsThreadSafe=true)
	Setup mutex for thread-safe allocations.
void *	Allocate (const size_t sizesize) override
	Allocate memory with given size. Returns NULL on failure.
void *	AllocateOptimal (const size_t sizesize) override
	Allocate memory with given size. Returns NULL on failure.
void	Free (void *) override
	Free a previously allocated memory. Does nothing.
	~NCollection_IncAllocator () override
	Destructor (calls Clean() internally).
void	Reset (const bool theReleaseMemory=false)
	Re-initialize the allocator so that the next Allocate call should start allocating in the very beginning as though the allocator is just constructed. Warning: make sure that all previously allocated data are no more used in your code!
Public Member Functions inherited from Standard_Transient
	Standard_Transient ()
	Empty constructor.
	Standard_Transient (const Standard_Transient &)
	Copy constructor – does nothing.
Standard_Transient &	operator= (const Standard_Transient &)
	Assignment operator, needed to avoid copying reference counter.
virtual	~Standard_Transient ()=default
	Destructor must be virtual.
virtual const opencascade::handle< Standard_Type > &	DynamicType () const
	Returns a type descriptor about this object.
bool	IsInstance (const opencascade::handle< Standard_Type > &theType) const
	Returns a true value if this is an instance of Type.
bool	IsInstance (const char *const theTypeName) const
	Returns a true value if this is an instance of TypeName.
bool	IsKind (const opencascade::handle< Standard_Type > &theType) const
	Returns true if this is an instance of Type or an instance of any class that inherits from Type. Note that multiple inheritance is not supported by OCCT RTTI mechanism.
bool	IsKind (const char *const theTypeName) const
	Returns true if this is an instance of TypeName or an instance of any class that inherits from TypeName. Note that multiple inheritance is not supported by OCCT RTTI mechanism.
Standard_Transient *	This () const
	Returns non-const pointer to this object (like const_cast). For protection against creating handle to objects allocated in stack or call from constructor, it will raise exception Standard_ProgramError if reference counter is zero.
int	GetRefCount () const noexcept
	Get the reference counter of this object.
void	IncrementRefCounter () noexcept
	Increments the reference counter of this object. Uses relaxed memory ordering since incrementing only requires atomicity, not synchronization with other memory operations.
int	DecrementRefCounter () noexcept
	Decrements the reference counter of this object; returns the decremented value. Uses release ordering for the decrement to ensure all writes to the object are visible before the count reaches zero. An acquire fence is added only when the count reaches zero, ensuring proper synchronization before deletion. This is more efficient than using acq_rel for every decrement.
virtual void	Delete () const
	Memory deallocator for transient classes.

Static Public Attributes
static constexpr size_t	THE_DEFAULT_BLOCK_SIZE = 1024 * 12
static constexpr size_t	THE_MINIMUM_BLOCK_SIZE = 1024 * 2

Protected Member Functions
void *	allocateSlow (const size_t theSize)
	Slow-path allocation: allocates a new block if needed, performs bump allocation, and reorders the block list. Must be called under mutex (when thread-safe) or without lock (when non-thread-safe).
void	increaseBlockSize ()
	Increases size according current block size level.
void	resetBlock (IBlock *theBlock) const
	Resets available size and CurPointer field.
void	clean ()
	Flush all previously allocated data. All pointers returned by Allocate() become invalid – be very careful with this.
Protected Member Functions inherited from NCollection_BaseAllocator
	NCollection_BaseAllocator () noexcept
	Constructor - prohibited.

Additional Inherited Members
Static Public Member Functions inherited from NCollection_BaseAllocator
static const occ::handle< NCollection_BaseAllocator > &	CommonBaseAllocator ()
	CommonBaseAllocator This method is designed to have the only one BaseAllocator (to avoid useless copying of collections). However one can use operator new to create more BaseAllocators, but it is injurious.
static constexpr const char *	get_type_name ()
	Returns a type descriptor about this object.
static const opencascade::handle< Standard_Type > &	get_type_descriptor ()
	Returns type descriptor of Standard_Transient class.

Detailed Description

Class NCollection_IncAllocator - incremental memory allocator. This class allocates memory on request returning the pointer to an allocated block. This memory is never returned to the system until the allocator is destroyed.

By comparison with the standard new() and malloc() calls, this method is faster and consumes very small additional memory to maintain the heap.

All pointers returned by Allocate() are aligned to the size of the data type "aligned_t". To modify the size of memory blocks requested from the OS, use the parameter of the constructor (measured in bytes); if this parameter is smaller than 25 bytes on 32bit or 49 bytes on 64bit, the block size will be the default 12 kbytes.

It is not recommended to use memory blocks larger than 16KB on Windows platform for the repeated operations because Low Fragmentation Heap is not going to be used for these allocations which may lead to memory fragmentation and the general performance slow down.

Note that this allocator is most suitable for single-threaded algorithms (consider creating dedicated allocators per working thread), and thread-safety of allocations is DISABLED by default (see SetThreadSafe()).

Member Enumeration Documentation

IBlockSizeLevel

enum class NCollection_IncAllocator::IBlockSizeLevel : unsigned short

strong

Description ability to next growing size each 5-th new block.

Enumerator
Min
Small
Medium
Large
Max

Constructor & Destructor Documentation

NCollection_IncAllocator()

NCollection_IncAllocator::NCollection_IncAllocator

(

const size_t

theBlockSize = THE_DEFAULT_BLOCK_SIZE

)

Constructor. Note that this constructor does NOT setup mutex for using allocator concurrently from different threads, see SetThreadSafe() method.

The default size of the memory blocks is 12KB. It is not recommended to use memory blocks larger than 16KB on Windows platform for the repeated operations (and thus multiple allocations) because Low Fragmentation Heap is not going to be used for these allocations, leading to memory fragmentation and eventual performance slow down.

~NCollection_IncAllocator()

NCollection_IncAllocator::~NCollection_IncAllocator ( )

override

Destructor (calls Clean() internally).

Member Function Documentation

Allocate()

void * NCollection_IncAllocator::Allocate ( const size_t size )

overridevirtual

Allocate memory with given size. Returns NULL on failure.

Reimplemented from NCollection_BaseAllocator.

AllocateOptimal()

void * NCollection_IncAllocator::AllocateOptimal ( const size_t size )

overridevirtual

Allocate memory with given size. Returns NULL on failure.

Reimplemented from NCollection_BaseAllocator.

allocateSlow()

void * NCollection_IncAllocator::allocateSlow ( const size_t theSize )

protected

Slow-path allocation: allocates a new block if needed, performs bump allocation, and reorders the block list. Must be called under mutex (when thread-safe) or without lock (when non-thread-safe).

clean()

void NCollection_IncAllocator::clean ( )

protected

Flush all previously allocated data. All pointers returned by Allocate() become invalid – be very careful with this.

Free()

void NCollection_IncAllocator::Free ( void * )

inlineoverridevirtual

Free a previously allocated memory. Does nothing.

Reimplemented from NCollection_BaseAllocator.

increaseBlockSize()

void NCollection_IncAllocator::increaseBlockSize ( )

protected

Increases size according current block size level.

Reset()

void NCollection_IncAllocator::Reset

(

const bool

theReleaseMemory = false

)

Re-initialize the allocator so that the next Allocate call should start allocating in the very beginning as though the allocator is just constructed. Warning: make sure that all previously allocated data are no more used in your code!

Parameters

theReleaseMemory

True - release all previously allocated memory, False - preserve it for future allocations.

resetBlock()

void NCollection_IncAllocator::resetBlock ( IBlock * theBlock ) const

protected

Resets available size and CurPointer field.

SetThreadSafe()

void NCollection_IncAllocator::SetThreadSafe

(

const bool

theIsThreadSafe = true

)

Setup mutex for thread-safe allocations.

Warning

Must not be called concurrently with Allocate/AllocateOptimal/Reset/clean on the same allocator instance; toggling the mutex while another thread holds a shared_lock on the fast path is undefined behaviour.

Field Documentation

THE_DEFAULT_BLOCK_SIZE

size_t NCollection_IncAllocator::THE_DEFAULT_BLOCK_SIZE = 1024 * 12

staticconstexpr

THE_MINIMUM_BLOCK_SIZE

size_t NCollection_IncAllocator::THE_MINIMUM_BLOCK_SIZE = 1024 * 2

staticconstexpr

---

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

• NCollection_IncAllocator.hxx