Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TRandomAccessStream
Inherited By:
TGrowingChunkyStream
Purpose:
TChunkyStream is a concrete class (derived from TRandomAccessStream) that embodies a random access stream backed by chunks of memory.
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.
- TChunkyStream ()
- TChunkyStream (TChunkyMemory * adoptChunkyMemory)
- TChunkyStream (const TChunkyStream & aChunkyStream)
Interface Category:
API.
Purpose:
- Default constructor.
- Creates a TChunkyStream that obtains memory chunks from a specific TChunkyMemory object.
- Copy constructor.
Calling Context:
- Called by the stream-in operators.
- Called to create a usable TChunkyStream.
- Called to copy an object.
Parameters:
Return Value:
None.
Exceptions:
The copy constructor throws TGeneralKernelException(kInsufficientMemory) if there is not enough memory to copy the source object. Otherwise, throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The copy constructor performs a deep copy of the source object.
Member Function: TChunkyStream::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.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TChunkyStream::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 TGeneralKernelException(kBadObject) if the stream was created with the default constructor and no value has been streamed into the TChunkyStream object.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TChunkyStream::operator=
TChunkyStream & operator =(const TChunkyStream & aChunkyStream)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
- const TChunkyStream & aChunkyStream -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:
This member function performs a deep copy of the source object.
virtual ~ TChunkyStream ()
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:
Not multithread safe.
Other Considerations:
Calling the destructor releases all memory allocated for the chunky memory and deletes the TChunkyMemory object used at construction time.
Member Function: TChunkyStream::SetChunkSize
virtual void SetChunkSize (size_t newChunkSize)
Interface Category:
API.
Purpose:
Sets the size of chunk to allocate when more memory is requested.
Calling Context:
Called to change the size of chunk allocated by the TChunkyStream.
Parameters:
- size_t chunkSize -The new size of chunk to allocate from the chunky memory.
Return Value:
None.
Exceptions:
Throws TGeneralKernelException(kBadArgument) if an invalid chunk size is passed.
Throws TGeneralKernelException(kBadObject) if the stream was created with the default constructor and no value has been streamed into the TChunkyStream object.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TChunkyStream::GetChunkSize
virtual size_t GetChunkSize () const
Interface Category:
API.
Purpose:
Returns the size of chunk to allocate when more memory is requested.
Calling Context:
Called to determine information about how the TChunkyStream object allocates new chunks.
Parameters:
Return Value:
A size_t that indicates the size of chunk that is allocated from the chunky memory.
Exceptions:
Throws TGeneralKernelException(kBadObject) if the stream was created with the default constructor and no value has been streamed into the TChunkyStream object.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TChunkyStream::GetTotalSize
virtual size_t GetTotalSize () const
Interface Category:
API.
Purpose:
Returns the length of the stream in bytes.
Calling Context:
Called to query the state of the TChunkyStream object.
Parameters:
Return Value:
A size_t that is the length of the stream in bytes.
Exceptions:
Throws TGeneralKernelException(kBadObject) if the stream was created with the default constructor and no value has been streamed into the TChunkyStream object.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TChunkyStream::GetPosition
virtual StreamPosition GetPosition () const
Interface Category:
API.
Purpose:
Returns the current stream position.
Calling Context:
Called to query the state of the TChunkyStream object.
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: TChunkyStream::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 TChunkyStream object.
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: TChunkyStream::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 TChunkyStream object.
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: TChunkyStream::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 TChunkyStream object.
Parameters:
Return Value:
Returns true if the first location of the stream is mapped read-only, otherwise, returns false.
Exceptions:
Throws TGeneralKernelException(kBadObject) if the stream was created with the default constructor and no value has been streamed into the TChunkyStream object.
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.
virtual void Seek (StreamPosition newPosition)
Interface Category:
API.
Purpose:
Sets the current stream position based on an absolute stream offset.
Calling Context:
Called to change the state of the TChunkyStream 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(kBadObject) if the stream was created with the default constructor and no value has been streamed into the TChunkyStream object.
Throws TGeneralKernelException(kHitPhysicalEndOfStream) if the new position is beyond the physical end of the stream.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TChunkyStream::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 TChunkyStream 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(kBadObject) if the stream was created with the default constructor and no value has been streamed into the TChunkyStream object.
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: TChunkyStream::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 TChunkyStream 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(kBadObject) if the stream was created with the default constructor and no value has been streamed into the TChunkyStream object.
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: TChunkyStream::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 TChunkyStream 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 TGeneralKernelException(kBadObject) if the stream was created with the default constructor and no value has been streamed into the TChunkyStream object.
Throws TGeneralKernelException(kInsufficientMemory) if there is not enough memory to allocate another chunk.
Concurrency:
Not multithread safe.
Other Considerations:
This member function causes memory to be allocated or deallocated depending on whether the stream is being lengthened or shortened.
Member Function: TChunkyStream::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 TGeneralKernelException(kHitPhysicalEndOfStream) if there is no more room in the stream.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TChunkyStream::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:
None.
Member Function: TChunkyStream::GetChunkCollection
virtual void GetChunkCollection (TCollectionOf < TMemorySurrogate > & theCollection)
Interface Category:
API.
Purpose:
Appends the chunks which comprise the chunky stream to the collection passed to the member function.
Calling Context:
Called to query the state of the TChunkyStream object.
Parameters:
Return Value:
None.
Exceptions:
Throws TGeneralKernelException(kBadObject) if the stream was created with the default constructor and no value has been streamed into the TChunkyStream object.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.