Class: TContiguousMemoryStream

Declaration: Memory.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TRandomAccessStream

Inherited By:

None.

Purpose:

TContiguousMemoryStream is a concrete class (derived from TRandomAccessStream) that uses contiguous memory supplied by the client.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derived classes of this class override its virtual member functions to implement the defined protocol.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TContiguousMemoryStream::TContiguousMemoryStream

TContiguousMemoryStream ()
TContiguousMemoryStream (const TMemorySurrogate & theRange)
TContiguousMemoryStream (const TContiguousMemoryStream &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a TContiguousMemoryStream that uses a specific range of contiguous memory.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to create a usable TContiguousMemoryStream.
Called to copy an object.

Parameters:

Takes no parameters.
const TMemorySurrogate & theRange -A TMemorySurrogate that describes the range of contiguous memory to use for the stream.
const TContiguousMemoryStream & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::operator=

TContiguousMemoryStream & operator =(const TContiguousMemoryStream & aContiguousMemoryStream)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TContiguousMemoryStream & aContiguousMemoryStream -The object that supplies the value for the right-hand side of the assignment statement.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::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 TInvalidVersionError if the object read in from the stream has an invalid version number. Throws TGeneralKernelException(kInsufficientMemory) if the destination TContiguousMemoryStream is too small to contain the TContiguousMemoryStream being streamed in.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::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:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::~TContiguousMemoryStream

virtual ~ TContiguousMemoryStream ()

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:

Not multithread safe.

Other Considerations:

This member function does not release the memory associated with the TContiguousMemoryStream.

Member Function: TContiguousMemoryStream::GetMemorySurrogate

virtual void GetMemorySurrogate (TMemorySurrogate & aRange) const

Interface Category:

API.

Purpose:

Returns a TMemorySurrogate that describes the memory that comprises the stream.

Calling Context:

Called to query the state of the TContiguousMemoryStream object.

Parameters:

TMemorySurrogate & aRange -The output parameter that receives the description of the memory that comprises the stream.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::GetPosition

virtual StreamPosition GetPosition () const

Interface Category:

API.

Purpose:

Returns the current stream position.

Calling Context:

Called to query the state of the TContiguousMemoryStream object.

Parameters:

Takes no parameters.

Return Value:

Returns a StreamPosition value that indicates the offset in the stream at which the next stream in or stream out will occur.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::GetLogicalEndOfStream

virtual StreamPosition GetLogicalEndOfStream () const

Interface Category:

API.

Purpose:

Returns the current logical end of stream position.

Calling Context:

Called to query the state of the TContiguousMemoryStream object.

Parameters:

Takes no parameters.

Return Value:

Returns a StreamPosition value that indicates the logical end of stream.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::GetPhysicalEndOfStream

virtual StreamPosition GetPhysicalEndOfStream () const

Interface Category:

API.

Purpose:

Returns the current physical end of stream position.

Calling Context:

Called to query the state of the TContiguousMemoryStream object.

Parameters:

Takes no parameters.

Return Value:

Returns a StreamPosition value that indicates the logical end of stream.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::GetReadOnly

virtual bool GetReadOnly () const

Interface Category:

API.

Purpose:

Determines if the stream is read-only.

Calling Context:

Called to query the state of the TContiguousMemoryStream object.

Parameters:

Takes no parameters.

Return Value:

Returns true if the first location of the stream is mapped read-only, otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function works on the presumption that all locations in the stream have the same memory access permissions. It is possible for a programmer to explicitly violate this condition, in which case, the value returned by this member function is useless.

Member Function: TContiguousMemoryStream::Seek

virtual void Seek (StreamPosition position)

Interface Category:

API.

Purpose:

Sets the current stream position based on an absolute stream offset.

Calling Context:

Called to change the state of the TContiguousMemoryStream object. This is usually done when initializing the stream or recovering from an exception.

Parameters:

StreamPosition newPosition -The new absolute stream position to set as the current position.

Return Value:

None.

Exceptions:

Throws TGeneralKernelException(kHitPhysicalEndOfStream) if the new position is beyond the physical end of the stream.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::SeekRelative

virtual void SeekRelative (StreamPositionDelta offset)

Interface Category:

API.

Purpose:

Sets the current stream position based on a relative stream offset from the current position.

Calling Context:

Called to change the state of the TContiguousMemoryStream object. This is usually done when initializing the stream or recovering from an exception.

Parameters:

StreamPositionDelta offset -The offset from the current position to use in setting the new current position.

Return Value:

None.

Exceptions:

Throws TGeneralKernelException(kBadArgument) if the offset plus the current position is less than zero or if the addition of the two values would overflow the precision of the StreamPosition data type. Throws TGeneralKernelException(kHitPhysicalEndOfStream) if the new position is beyond the physical end of the stream.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::SetLogicalEndOfStream

virtual void SetLogicalEndOfStream (StreamPosition thePosition)

Interface Category:

API.

Purpose:

Sets the logical end of stream position.

Calling Context:

Called to change the state of the TContiguousMemoryStream object. This is usually done when initializing the stream or recovering from an exception.

Parameters:

StreamPosition thePosition -The position at which to set the logical end of stream.

Return Value:

None.

Exceptions:

Throws TGeneralKernelException(kHitPhysicalEndOfStream) if the new logical end of stream is beyond the physical end of the stream.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousMemoryStream::SetPhysicalEndOfStream

virtual void SetPhysicalEndOfStream (StreamPosition thePosition)

Interface Category:

API.

Purpose:

Sets the physical end of stream position.

Calling Context:

Called to change the state of the TContiguousMemoryStream object. This is usually done when initializing the stream or recovering from an exception.

Parameters:

StreamPosition thePosition -The position at which to set the physical end of stream.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function does not throw any errors. It is presumed that if the client has passed in a memory surrogate that describes the streams memory, then the client is also knowledgeable enough to change the memory range.

Member Function: TContiguousMemoryStream::AllocateForWrite

virtual void AllocateForWrite (StreamPosition desiredByteCount)

Interface Category:

Completes stream-out operations that overflow the current stream buffer.

Calling Context:

Called by primitive streaming operators when there is not enough memory left in the current stream buffer to complete a stream-out operation.

Parameters:

StreamPosition desiredByteCount -The number of bytes that must be written to the stream.

Return Value:

None.

Exceptions:

Throws TGeneralKernelException(kHitPhysicalEndOfStream) if there is no more room in the stream.

Concurrency:

API.

Other Considerations:

This member function always throws an exception because the current stream buffer is the same as the contiguous memory range that comprises the stream.

Member Function: TContiguousMemoryStream::AllocateForRead

virtual void AllocateForRead (StreamPosition desiredByteCount)

Interface Category:

API.

Purpose:

Completes stream-in operations that hit the end of the current stream buffer.

Calling Context:

Called by primitive streaming operators when there is not enough data left in the current stream buffer to complete a stream-in operation.

Parameters:

StreamPosition desiredByteCount -The number of bytes that must be read from the stream.

Return Value:

None.

Exceptions:

Throws TGeneralKernelException(kHitLogicalEndOfStream) if the stream-in operation can read beyond the logical end of stream.

Concurrency:

Not multithread safe.

Other Considerations:

This member function always throws an exception because the current stream buffer is the same as the contiguous memory range that comprises the stream.

Member Function: TContiguousMemoryStream::UseNewMemory

virtual void UseNewMemory (const TMemorySurrogate & newMemoryToUse, StreamPosition newLogicalEndOfStream)

Interface Category:

API.

Purpose:

Changes the memory used by the stream also sets new logical end of stream.

Calling Context:

Called to to change the backing memory for the stream.

Parameters:

const TMemorySurrogate & newMemoryToUse -the new memory to be used.
StreamPosition newLogicalEndOfStream -new logical end of stream to be used.

Return Value:

None.

Exceptions:

Throws TStreamException::kHitPhysicalEndOfStream if incorrect value for newLogicalEndOfStream is passed.

Concurrency:

Not multithread safe.

Other Considerations:

this member function will change the memory used by the TContiguousMemoryStream object to newMemoryToUse. It will set 1) the physical end of stream to the length of the memory surrogate passed, 2) the logical end of stream to newLogicalEndOfStream value passed, and 3) the current stream position to zero.

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