Class: TContiguousGrowingStream

Declaration: Memory.h

Taxonomy Categories:

Member Functions:

TContiguousGrowingStream
operator=
operator<<=
operator>>=
~TContiguousGrowingStream
GetMemorySurrogate
GetPosition
GetLogicalEndOfStream
GetPhysicalEndOfStream
GetReadOnly
Seek
SeekRelative
SetLogicalEndOfStream
SetPhysicalEndOfStream
AllocateForWrite
AllocateForRead

Interface Category:

API.

Inherits From:

TRandomAccessStream

Inherited By:

None.

Purpose:

Provides a contiguous memory stream that also grows.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TContiguousGrowingStream::TContiguousGrowingStream

TContiguousGrowingStream ()
TContiguousGrowingStream (TMemoryHeap &, size_t chunkSize =kDefaultChunkSize)
TContiguousGrowingStream (const TContiguousGrowingStream &)

Interface Category:

API.

Purpose:

Default constructor.
Constructor that decides which memory heap is used for allocation, and what is the default chunk size to grow.
Copy constructor.

Calling Context:

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

Parameters:

Takes no parameters.
TMemoryHeap & -The memory heap to be used.
size_t chunkSize =kDefaultChunkSize -The default size of chunk to be used for growing.
const TContiguousGrowingStream & -The stream to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousGrowingStream::operator=

TContiguousGrowingStream & operator =(const TContiguousGrowingStream &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TContiguousGrowingStream & -The left hand side of the assignment operation.

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: TContiguousGrowingStream::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:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousGrowingStream::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: TContiguousGrowingStream::~TContiguousGrowingStream

virtual ~ TContiguousGrowingStream ()

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:

None.

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

The memory surrogate returned is valid only till next operation on the same stream.

Member Function: TContiguousGrowingStream::GetPosition

virtual StreamPosition GetPosition () const

Interface Category:

API.

Purpose:

Returns the current stream position.

Calling Context:

Called to query the state of the TContiguousGrowingStream 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: TContiguousGrowingStream::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 TContiguousGrowingStream 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: TContiguousGrowingStream::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 TContiguousGrowingStream 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: TContiguousGrowingStream::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 TContiguousGrowingStream 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: TContiguousGrowingStream::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 TContiguousGrowingStream 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 no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousGrowingStream::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 TContiguousGrowingStream 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.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousGrowingStream::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 TContiguousGrowingStream 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 no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousGrowingStream::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 TContiguousGrowingStream 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.

Member Function: TContiguousGrowingStream::AllocateForWrite

virtual void AllocateForWrite (StreamPosition desiredByteCount)

Interface Category:

API.

Purpose:

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 no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TContiguousGrowingStream::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 no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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