Class: TStandardMemoryHeap

Declaration: StandardMemoryHeap.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TMemoryHeap

Inherited By:

TLocalMemoryHeap TSharedMemoryHeap

Purpose:

TStandardMemoryHeap is the abstract base class of the two concrete storage allocator classes, TLocalMemoryHeap and TSharedMemoryHeap. In addition to providing the features of TMemoryHeap, TStandardMemoryHeap supports the association of TMemoryHook objects to monitor heap usage. The support of TMemoryHook is specific to the standard concrete Taligent classes and is not a part of the basic interface for Taligent storage allocators.

Instantiation:

Abstract base class; cannot be instantiated.

Deriving Classes:

Do not derive any classes from TStandardMemoryHeap.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TStandardMemoryHeap::~TStandardMemoryHeap

virtual ~ TStandardMemoryHeap ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called by clients of TStandardMemoryHeap to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TBadUseOfMemoryHeap if the heap is read-only in this task.

Concurrency:

Multithread safe.

Other Considerations:

The Heap framework makes one distinguished instance the master object. Therefore, deleting a nonmaster object does not delete the heap itself.

Member Function: TStandardMemoryHeap::Allocate

virtual void * Allocate (size_t size)

Interface Category:

API.

Purpose:

Allocates a new block of at least the specified size. An allocator can allocate a larger size block, in which case, no record of the originally requested size is kept. If the size is zero, a unique pointer is returned, which conforms to the proposed C++ standard.

Calling Context:

Called to allocate a block of storage.

Parameters:

size_t size -The minimum number of bytes to allocate.

Return Value:

Returns a pointer to block allocated.

Exceptions:

Throws TBadUseOfMemoryHeap if the heap is read-only. Throws TMemoryHeapExhausted if insufficient memory exists to satisfy the request. Other exceptions can be passed through.

Concurrency:

Multithread safe.

Other Considerations:

TLocalMemoryHeaps grow beyond their original size to satisfy allocation requests and only throw a TMemoryHeapExhausted exception if insufficient space exists in the system to satisfy the allocation request. TSharedMemoryHeaps do not grow, and throw TMemoryHeapExhausted when full.

Member Function: TStandardMemoryHeap::BlockSize

virtual size_t BlockSize (const void * block) const

Interface Category:

API.

Purpose:

Returns the size, in bytes, of the specified allocated block. This member function is valid only for allocated blocks.

Calling Context:

Called to obtain the size of an allocated block.

Parameters:

const void * block -The allocated block whose size is to be obtained.

Return Value:

Returns the size in bytes of the specified allocated block.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

The results of this member function are undefined if the block parameter provided does not point to the beginning of an allocated block within this heap.

Member Function: TStandardMemoryHeap::BytesAllocated

virtual size_t BytesAllocated () const

Interface Category:

API.

Purpose:

Returns the total number of bytes allocated for this heap.

Calling Context:

Called to determine the number of bytes allocated for this heap.

Parameters:

Takes no parameters.

Return Value:

Returns the total number of bytes allocated for this heap, including the space used by the heap itself.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardMemoryHeap::Check

virtual void Check () const

Interface Category:

API.

Purpose:

Runs a consistency check on the heap to detect possible corruption of the heap's internal state and throws an exception if any inconsistencies are found. Successful completion of this member function does not guarantee that the heap is consistent. An exception can be thrown even though the heap is not corrupted.

Calling Context:

Called to check the consistency of the heap.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TChunkyHeapCorrupted or TTreeHeapCorrupted if the heap is corrupted. Other exceptions can be passed through.

Concurrency:

Multithread safe.

Other Considerations:

The accuracy of Check can be improved by ensuring that all other threads in the tasks are suspended while Check executes. Even so, a suspended thread could be in the middle of a heap allocate or delete operation and this could lead Check to erroneously conclude that the heap is corrupt.

Member Function: TStandardMemoryHeap::CreateIterator

virtual TMemoryHeapIterator * CreateIterator () const

Interface Category:

API.

Purpose:

Creates an iterator for the blocks in the heap.

Calling Context:

Called by clients of TStandardMemoryHeap.

Parameters:

Takes no parameters.

Return Value:

Returns an iterator for the blocks in the heap.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardMemoryHeap::Free

virtual void Free (void *)

Interface Category:

API.

Purpose:

Frees the space to which the parameter refers. An exception is raised if the block is not an address of a previously allocated block in the address space managed by this heap object.

Calling Context:

Called to free a block of storage.

Parameters:

void * -A pointer to the block to be freed.

Return Value:

None.

Exceptions:

Throws TBadUseOfMemoryHeap if the heap is read-only. Other exceptions can be passed through.

Concurrency:

Multithread safe.

Other Considerations:

The results of this member function are undefined if the block parameter provided does not point to the beginning of an allocated block within this heap.

Member Function: TStandardMemoryHeap::GetBlockReuse

virtual bool GetBlockReuse () const

Interface Category:

API.

Purpose:

Returns true if reuse of previously allocated blocks is currently allowed.

Calling Context:

Called to determine if reuse of previously allocated blocks is allowed.

Parameters:

Takes no parameters.

Return Value:

Returns true if reuse of previously allocated blocks is allowed.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardMemoryHeap::IsWriteEnabled

virtual bool IsWriteEnabled () const

Interface Category:

API.

Purpose:

Returns true if the heap is writable in the current task. Returns false if the heap is read-only in the current task.

Calling Context:

Called by clients of TStandardMemoryHeap.

Parameters:

Takes no parameters.

Return Value:

Returns true if write permission for the heap is set in the current task.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardMemoryHeap::NumberAllocatedBlocks

virtual size_t NumberAllocatedBlocks () const

Interface Category:

API.

Purpose:

Returns the number of allocated blocks in this heap.

Calling Context:

Called by clients of TStandardMemoryHeap.

Parameters:

Takes no parameters.

Return Value:

Returns the number of allocated blocks in this heap.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Zero is returned if the heap's segments have not been created or if the heap is empty.

Member Function: TStandardMemoryHeap::Reset

virtual void Reset ()

Interface Category:

API.

Purpose:

Reinitializes the heap and deletes all allocated blocks. The heap might still contain blocks that it allocates for its internal management. Calling Reset is logically equivalent to destroying the heap (without destroying the objects contained in the heap), and constructing a new heap identical to the original one.

Calling Context:

Called by clients of TStandardMemoryHeap.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TBadUseOfMemoryHeap if write permission is not set in the current task.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardMemoryHeap::Reallocate

virtual void * Reallocate (void * block, size_t newSize)

Interface Category:

API.

Purpose:

Reallocates the specified block to at least the specified size. In some cases, the block cannot be resized, but the block returned is at least as big as the new size specified. If the address of the block is not in the space managed by this heap object, an exception is raised. If the new size is smaller, the data from the higher address end of the block is lost. The address of a block can change after it is reallocated, even if the new size is smaller than the original size. If the parameter block is NIL, a block of the new size is allocated.

Calling Context:

Called by clients of TStandardMemoryHeap.

Parameters:

void * block -The address of the block to reallocate.
size_t newSize -The minimum size of the new block.

Return Value:

void * -The address of the new block.

Exceptions:

Throws TBadUseOfMemoryHeap if write permission is not set in the current task.

Concurrency:

Multithread safe.

Other Considerations:

The results of this member function are undefined if the block parameter provided does not point to the beginning of an allocated block within this heap and if the pointer is not NIL.

Member Function: TStandardMemoryHeap::SetWriteEnabled

virtual void SetWriteEnabled (bool =true)

Interface Category:

API.

Purpose:

Enables or disables write permission for the heap in the current task's address space.

Calling Context:

Called by clients of TStandardMemoryHeap.

Parameters:

bool =true -true enables writing and false disables writing.

Return Value:

None.

Exceptions:

Throws TBadUseOfMemoryHeap exception if the heap's creator did not set its write protection modifiable and the current task is not the creator.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardMemoryHeap::SetBlockReuse

virtual void SetBlockReuse (bool =true)

Interface Category:

API.

Purpose:

A debugging tool that enables or disables the reuse of previously allocated blocks. When set to false, the allocator ceases to delete blocks; in effect, causing a storage leak.

Calling Context:

Called by clients of TStandardMemoryHeap.

Parameters:

bool =true -true enables the reuse of blocks and false disables the reuse of freed blocks.

Return Value:

None.

Exceptions:

Throws TBadUseOfMemoryHeap if the heap is not write enabled, passes other exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardMemoryHeap::IsZapping

virtual bool IsZapping () const

Interface Category:

API.

Purpose:

Returns true if newly allocated blocks are initialized to a specific value. The default implementation always returns false.

Calling Context:

Called by clients of TStandardMemoryHeap.

Parameters:

Takes no parameters.

Return Value:

Returns true if zapping is turned on.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

TStandardMemoryHeap implements zapping such that it can be turned on and off repeatedly.

Member Function: TStandardMemoryHeap::SetZapping

virtual void SetZapping (bool doZap =false)

Interface Category:

API.

Purpose:

Enables or disables zapping for a heap. If doZap is true, allocated and free blocks are set to a certain value.

Calling Context:

Called by clients of TStandardMemoryHeap.

Parameters:

bool doZap =false -Don't do zapping; true -Do zapping.

Return Value:

None.

Exceptions:

Throws TBadUseOfMemoryHeap if the heap is read-only. Other exceptions can be passed through.

Concurrency:

Multithread safe.

Other Considerations:

TStandardMemoryHeap implements zapping such that it can be turned on and off repeatedly.

Member Function: TStandardMemoryHeap::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called by clients of TStandardMemoryHeap.

Parameters:

Takes no parameters.

Return Value:

Returns the hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardMemoryHeap::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Local heaps can only be streamed same-task. Shared heaps can be streamed same-task or same-session. Heaps cannot be streamed deep freeze.

Member Function: TStandardMemoryHeap::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Local heaps can only be streamed same-task. Shared heaps can be streamed same-task or same-session. Heaps cannot be streamed deep freeze.

Click the icon to mail questions or corrections about this material to Taligent personnel.