Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MCollectible
Inherited By:
TStandardMemoryHeap
Purpose:
TMemoryHeap is a class that provides for the allocation and freeing of nonrelocatable storage, without compaction or garbage collection. TMemoryHeap maintains the storage for C++ objects through the operators new and delete. TMemoryHeap also maintains storage allocated by C library functions such as malloc or free.
A task can have more than one heap. Each heap consists of one or more memory segments from which blocks of memory can be allocated and freed.
TMemoryHeaps are multithread safe and efficient. They effectively handle very large heaps and provide simple error handling.
A heap typically obtains memory segments from the kernel and can allocate in shared memory so that objects can be shared among tasks.
TMemoryHeaps also provides debugging aids. The TMemoryHeapIterator class can be used to iterate through the allocated or free blocks in a heap.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
TMemoryHeap provides an implementation of a standard heap. You can derive classes from TMemoryHeap to create your own special-purpose heaps.
Concurrency:
Multithread safe.
Resource Use:
No special requirements.
Other Considerations:
None.
virtual ~ TMemoryHeap ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::Allocate
virtual void * Allocate (size_t size)
Interface Category:
API.
Purpose:
A pure virtual member function that allocates a new block of at least the size specified. A larger size block can be allocated, in which case, no record is kept of the originally requested size. A unique pointer is returned if the requested size is zero, which conforms to the proposed C++ standard.
Calling Context:
Called to allocate a block of storage.
Parameters:
- size_t size -The minimum size to be allocated.
Return Value:
Returns a pointer to block allocated.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
Deriving classes should override this member function.
Member Function: TMemoryHeap::BlockSize
virtual size_t BlockSize (const void * block) const
Interface Category:
API.
Purpose:
A pure virtual member function that returns the size, in bytes, of the specified block. It is assumed that the block parameter points to the start of a block in this heap.
Calling Context:
Called by clients of TMemoryHeap.
Parameters:
- const void * block -The block whose size is to be returned.
Return Value:
Returns the size, in bytes, of the specified 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 a block within this heap.
Deriving classes should override this member function.
Member Function: TMemoryHeap::BytesAllocated
virtual size_t BytesAllocated () const
Interface Category:
API.
Purpose:
A pure virtual function that returns the total number of bytes allocated for this heap, including the space used by the heap itself.
Calling Context:
Called to determine the amount of space used in a given heap.
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:
Deriving classes should override this member function.
Member Function: TMemoryHeap::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 might be thrown even though the heap is not corrupted.
Calling Context:
Called to check the consistency of the heap.
Parameters:
Return Value:
None.
Exceptions:
Throws TMemoryHeapException if the heap is corrupted or if an error is encountered.
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 can 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: TMemoryHeap::CreateIterator
virtual TMemoryHeapIterator * CreateIterator () const
Interface Category:
API.
Purpose:
Creates an iterator for the blocks in this heap.
Calling Context:
Called by a client of TMemoryHeap to create an iterator for the blocks in this heap.
Parameters:
Return Value:
Returns an iterator for the blocks in this heap.
Exceptions:
Throws TMemoryHeapException if the heap is corrupted or if an error is encountered.
Concurrency:
Multithread safe.
Other Considerations:
Deriving classes should override this member function.
Member Function: TMemoryHeap::Free
virtual void Free (void *)
Interface Category:
API.
Purpose:
A pure virtual member function that frees the space to which the parameter refers. It is assumed that the parameter points to the beginning of a previously allocated block in the address space managed by this heap object.
Calling Context:
Called to free the specified storage.
Parameters:
- void * -A pointer to the block to be freed.
Return Value:
None.
Exceptions:
Throws TMemoryHeapException if the heap is corrupted or if an error is encountered.
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 a block previously allocated in this heap.
Deriving classes should override this member function.
Member Function: TMemoryHeap::GetBlockReuse
virtual bool GetBlockReuse () const
Interface Category:
API.
Purpose:
Returns true if previously allocated blocks are allowed to be reused. The default implementation always returns true.
Calling Context:
Called to determine if previously allocated heap blocks are allowed to be reused.
Parameters:
Return Value:
Returns true if previously allocated blocks are reused, otherwise, returns false.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::GetDefaultHeap
static TLocalMemoryHeap * GetDefaultHeap ()
Interface Category:
API.
Purpose:
Returns a pointer to the default local memory heap. Every task has a default local memory heap.
Calling Context:
Called by clients of TMemoryHeap.
Parameters:
Return Value:
Returns the default heap.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::GetMemoryHeaps
static void GetMemoryHeaps (TCollectionOf < TMemoryHeap > &)
Interface Category:
API.
Purpose:
Returns the set of heaps currently accessible to this task in the TCollectionOf parameter.
Calling Context:
Called by clients of TMemoryHeap.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
The set of memory heaps accessible to a task can change over time. If a new heap is created or an existing heap is deleted in this task's address space after a call to this member function, then the collection returned no longer contains an accurate set of heaps accessible to this task.
Member Function: TMemoryHeap::HeapOf
static TMemoryHeap * HeapOf (const void * block)
Interface Category:
API.
Purpose:
Returns a pointer to the heap object from which the supplied block is allocated. A NIL pointer is returned if block is not an address that is managed by any heap.
Calling Context:
Called by clients of TMemoryHeap.
Parameters:
- const void * block -A pointer to a block whose heap is to be determined.
Return Value:
Returns a pointer to the heap object from which the supplied block is allocated. A NIL pointer is returned if the block parameter is not an address managed by any heap.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
The pointer returned by this member function points to a heap object in use by the Memory Heap framework and must not be deleted. Multiple copies of a heap object can exist, so you should not use heap objects pointers to compare heap objects for equality.
Member Function: TMemoryHeap::IsWriteEnabled
virtual bool IsWriteEnabled () const
Interface Category:
API.
Purpose:
Determines if write permission is set for this heap. The default implementation always returns true.
Calling Context:
Called to check the write permission of this heap.
Parameters:
Return Value:
Returns true if write permission is set for this heap.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::NumberAllocatedBlocks
virtual size_t NumberAllocatedBlocks () const
Interface Category:
API.
Purpose:
A pure virtual member function that returns the number of blocks currently allocated in the heap. This count includes the number of blocks, if any, allocated by the heap for its internal management.
Calling Context:
Called to find out the number of blocks allocated in the heap.
Parameters:
Return Value:
Returns the number of distinct blocks currently allocated in the heap. The default implementation always returns zero.
Exceptions:
Throws TMemoryHeapException if the heap is corrupted or if an error is encountered.
Concurrency:
Multithread safe.
Other Considerations:
Deriving classes should override this member function.
Member Function: TMemoryHeap::Reset
virtual void Reset ()
Interface Category:
API.
Purpose:
A pure virtual member function that provides for the fast deletion of all the user allocated blocks in the heap. The heap can 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 to free all allocated blocks in the heap and reset the heap to a default state.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
The heap can still contain blocks that it allocated for its internal management.
Deriving classes should override this member function.
Member Function: TMemoryHeap::Reallocate
virtual void * Reallocate (void * block, size_t newSize)
Interface Category:
API.
Purpose:
A pure virtual member function that reallocates the specified block to at least the specified size. In some cases, the block might not 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 block parameter is NIL, a block of the new size is allocated.
Calling Context:
Called to reallocate a block of memory to a smaller or larger size.
Parameters:
- void * block -The address of the block to reallocate.
- size_t newSize -The requested size of the new block.
Return Value:
void * -The address of the new block.
Exceptions:
Throws TMemoryHeapException if the heap is corrupted or if an error is encountered.
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 a block within this heap.
Deriving classes should override this member function.
Member Function: TMemoryHeap::ReallocateAny
static void * ReallocateAny (void * block, size_t newSize)
Interface Category:
API.
Purpose:
Determines the heap in which the block is allocated and reallocates the block in the space managed by that heap object. If the block parameter is not NIL and is not in the address space managed by any heap object, an exception is raised. If the block parameter is NIL, a block of the specified size is allocated in the default heap. When a block of size zero is allocated, the block parameter is filled with a NIL pointer.
Calling Context:
Called to reallocate a block that is contained in any heap.
Parameters:
- void * block -A pointer to the block to reallocate.
- size_t newSize -The requested size of the new block.
Return Value:
None.
Exceptions:
Throws TMemoryHeapException if the heap is corrupted or if an error is encountered.
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 a heap block.
The address of a block can change after it is reallocated, even if the new size is smaller than the original size. You should not allocate a block of size zero in a specific heap and later call ReallocateAny and expect the new block to be allocated in the same heap.
Member Function: TMemoryHeap::SetWriteEnabled
virtual void SetWriteEnabled (bool =true)
Interface Category:
API.
Purpose:
Sets the heap's write permission to the specified value. If the value specified is false, the heap will be accessible in read-only mode.
Calling Context:
Called by a client of TMemoryHeap to set the write permission of the heap.
Parameters:
- bool =true -The write permission.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
If write permission is not set, the heap is accessible in read-only mode and only the const member functions are valid. Invoking anything other than const member functions can cause a hardware exception.
Member Function: TMemoryHeap::SetBlockReuse
virtual void SetBlockReuse (bool =true)
Interface Category:
API.
Purpose:
This member function is 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. By default, reuse of previously allocated blocks is permitted.
Calling Context:
Called to enable or disable the reuse of blocks.
Parameters:
- bool =true -Enables the reuse of blocks, if true.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
If block reuse is disabled and then later enabled, some blocks might not be able to be reclaimed, at the discretion of the heap.
Member Function: TMemoryHeap::IsZapping
virtual bool IsZapping () const
Interface Category:
API.
Purpose:
Returns true if allocated and free blocks are initialized to a certain value. The default implementation always returns false.
Calling Context:
Called to check the zap status of the heap.
Parameters:
Return Value:
Returns true if allocated and free blocks are set to a certain value, otherwise returns false.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::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. The default implementation does nothing.
Calling Context:
Called to set the zap status of a heap.
Parameters:
- bool doZap =If true, turns on heap zapping.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
Deriving classes should override this member function.
Member Function: TMemoryHeap::AddToGlobalHeapList
static void AddToGlobalHeapList (TMemoryHeap *)
Interface Category:
API.
Purpose:
Notifies the Heap framework that a heap is going into service.
Calling Context:
Called by classes derived from TMemoryHeap to notify the Heap framework that a heap is going into service.
Parameters:
- TMemoryHeap * -The heap to add to the global heap list.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::IsMyBlock
virtual bool IsMyBlock (const void *) const
Interface Category:
API.
Purpose:
A pure virtual member function that returns true if the specified address is in the range of the address space managed by this memory heap.
Calling Context:
Called to determine if this heap owns the specified block of memory.
Parameters:
- const void * -The address of the block to check.
Return Value:
Returns true if the specified address is in the range of the address space managed by this memory heap.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
Deriving classes should override this member function.
Member Function: TMemoryHeap::RemoveFromGlobalHeapList
static bool RemoveFromGlobalHeapList (TMemoryHeap *)
Interface Category:
API.
Purpose:
Notifies the Heap framework that a master heap is being taken out of service.
Calling Context:
Called by classes derived from TMemoryHeap, typically their destructor.
Parameters:
- TMemoryHeap * -The heap to remove from the global heap list.
Return Value:
Returns true if the heap is removed from the global heap list.
Exceptions:
Throws TMemoryHeapException if the heap is corrupted or if an error is encountered.
Concurrency:
Multithread safe.
Other Considerations:
None.
- TMemoryHeap ()
- TMemoryHeap (const TMemoryHeap &)
Interface Category:
API.
Purpose:
- Default constructor.
- Copy constructor.
Calling Context:
- Called to create a TMemoryHeap object.
- Called to copy an object.
Parameters:
- Takes no parameters.
- const TMemoryHeap & -The heap object to copy.
Return Value:
None.
Exceptions:
Throws TMemoryHeapException if the heap is corrupted or if an error is encountered.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::operator=
TMemoryHeap & operator =(const TMemoryHeap &)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
- const TMemoryHeap & -The heap object to assign to this heap.
Return Value:
A non-const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all through exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::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 through exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::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 through exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::GetNextCopy
TMemoryHeap * GetNextCopy ()
Interface Category:
API.
Purpose:
Returns a reference to the next copy of the heap.
Calling Context:
Called to obtain a reference to the next copy of the heap.
Parameters:
Return Value:
Returns a reference to the next copy of the heap. A NIL reference is returned if there are no more copies of the heap.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TMemoryHeap::GetFirstCopy
TMemoryHeap * GetFirstCopy ()
Interface Category:
API.
Purpose:
Returns a reference to the master copy of the heap. There should always be at least two copies of a heap, the master copy and the original.
Calling Context:
Called to obtain a reference to the master copy of the heap.
Parameters:
Return Value:
Returns a reference to the master copy of the heap.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
If this member function is called before a heap has been added to the master heap list, its master pointer is NIL.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.