Class: TSharedMemoryHeap

Declaration: StandardMemoryHeap.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TStandardMemoryHeap

Inherited By:

None.

Purpose:

TSharedMemoryHeap is a class that implements a heap that can be shared among tasks and across address spaces. One task is responsible for creating the shared heap and then knowledge of the heap is passed to other tasks using the standard streaming operators. Only a description of the kernel memory segment managed by the heap object is passed in the stream. The contents of the heap are not streamed. Shared memory heaps do not have global names and, therefore, a task cannot request to stream in an existing shared memory heap by name.

Instantiation:

Always allocate on the heap.

Deriving Classes:

Do not derive any classes from TSharedMemoryHeap.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TSharedMemoryHeap::TSharedMemoryHeap

TSharedMemoryHeap (size_t maxBytes)
TSharedMemoryHeap ()
TSharedMemoryHeap (const TSharedMemoryHeap &)

Interface Category:

API.

Purpose:

Creates a new shared heap of the specified size. Specify TSharedMemoryHeap::kDefaultSize for a default large heap size.
Default constructor. Creates a new default size shared heap. Use this constructor for stream in.
Copy constructor. Assigns this shared heap object to refer to the same kernel memory segment as the specified shared heap object.

Calling Context:

Called by clients of TLocalMemoryHeap.
Called by the stream-in operators
Called to copy an object.

Parameters:

size_t maxBytes -The initial size of the heap. The heap won't grow larger.
Takes no parameters.
const TSharedMemoryHeap & -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Shared heaps don't grow, due to the complexity of synchronizing all instances of shared heaps in all address spaces. It is the responsibility of the shared heap creator to ensure that the heap is big enough to satisfy all allocation requests.

Member Function: TSharedMemoryHeap::~TSharedMemoryHeap

virtual ~ TSharedMemoryHeap ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Only the destruction of the last instance of a TSharedMemoryHeap in all address spaces releases the heap's storage.

Member Function: TSharedMemoryHeap::IsWriteEnabled

virtual bool IsWriteEnabled () const

Interface Category:

API.

Purpose:

Returns true if write permission for the shared heap is set in the current task. Returns false if the shared heap is read-only in the current task.

Calling Context:

Called by clients of TSharedMemoryHeap.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSharedMemoryHeap::IsWriteProtectionModifiable

virtual bool IsWriteProtectionModifiable () const

Interface Category:

API.

Purpose:

Returns true if the current task can modify the write protection of the shared heap. Returns false if the current task cannot modify the write protection of the shared heap.

Calling Context:

Called by clients of TSharedMemoryHeap.

Parameters:

Takes no parameters.

Return Value:

Returns true if the current task can modify the write protection of the shared heap; returns false if the current task cannot modify the write protection of the shared heap.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Write protection is always modifiable in the task that created the shared heap.

Member Function: TSharedMemoryHeap::SetWriteEnabled

virtual void SetWriteEnabled (bool =true)

Interface Category:

API.

Purpose:

Enables write permission for the shared heap in the current task's address space if true is specified. Sets the shared heap write permission to read-only in the current task's address space if false is specified. If the write protection of the shared heap is not modifiable and the current task did not create the shared heap, an exception is raised.

Calling Context:

Called by clients of TSharedMemoryHeap.

Parameters:

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

Return Value:

None.

Exceptions:

Throws TBadUseOfMemoryHeap(kNonCreatorCannotModifyWriteProtection) if the write protection of the heap is not modifiable by this task.

Concurrency:

Multithread safe.

Other Considerations:

To promote security and reliability, shared heaps should only be writable in one task.

Member Function: TSharedMemoryHeap::SetWriteProtectionModifiable

virtual void SetWriteProtectionModifiable (bool =true)

Interface Category:

API.

Purpose:

Allows all tasks that access the shared heap to modify the write protection of the shared heap if true is specified. Only the task that created the shared heap is allowed to modify the write protection of the shared heap if false is specified.

Calling Context:

Called by the creator of a TSharedMemoryHeap to allow or disallow modification of the heap's write protection in other tasks.

Parameters:

bool =true -true allows all tasks to modify the write protection of the heap.

Return Value:

None.

Exceptions:

Throws TBadUseOfMemoryHeap(kNonCreatorCannotModifyWriteProtection) if a task other than the creator calls this function.

Concurrency:

Multithread safe.

Other Considerations:

To promote security and reliability, shared heaps should only be writable by the creating task. Shared heap creators should normally call SetWriteProtectionModifiable(false) before streaming a shared heap to another address space.

Member Function: TSharedMemoryHeap::operator=

TSharedMemoryHeap & operator =(const TSharedMemoryHeap &)

Interface Category:

API.

Purpose:

Assigns this shared heap object to refer to the same kernel memory segment as the specified shared heap object. If the original shared heap object is the last copy of that heap in this task's address space, the kernel segments for the original heap are closed in this task's address space.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TSharedMemoryHeap & -A heap handle to copy.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSharedMemoryHeap::operator>>=

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

Interface Category:

API.

Purpose:

Writes a description of the shared heap to the specified stream. In order for two or more tasks to share a heap, the task that created the shared heap must stream out a description of the shared heap. Cooperating tasks then stream in the shared heap description. The stream-in operator opens the shared heap at the same address in their respective address spaces as the task that created the heap.

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:

None.

Member Function: TSharedMemoryHeap::operator<<=

TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Reads a description of a shared heap from the specified stream and opens the heap's memory segments at the same logical address in this task's address space as the heap's creating task.

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:

When a shared heap is streamed in, its write protection is the same as it was in the task in which the heap was streamed out. Once a heap has been streamed in, the receiving task can refer to objects in the shared heap using regular pointers.

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