FOUNDATION SERVICES - Creating a TChunkyStream

Creating a TChunkyStream

Before you can write anything to a stream, you must instantiate a stream. This involves three steps: Create the memory used to back the stream; attach this memory to a virtual memory wrapper such as an instance of THeapChunkyMemory. Finally; create a memory stream specifying the instance of THeapChunkyMemory virtual memory to be associated with the stream.

As this code can appear complicated here is a walkthrough of each step.

Create some memory.
You could do this in two statements, but three are shown to emphasize that the data type of the argument passed to the constructor for TLocalMemoryHeap is size_t. The abbreviated form looks like this.
The pointer memHeap now refers to 1000 bytes of local heap storage.
Instantiate a THeapChunkyMemory referencing the memory.
You now have an instance of THeapChunkyMemory that acts as an interface for managing the underlying memory. The THeapChunkyMemory object can now be handed to a constructor for a memory stream.
Instantiate a TChunkyStream referring to the THeapChunkyMemory object.

Flattening an object to a stream

You can now use the stream. The first thing you'll want to do before streaming any objects out, is to set the physical end of memory for the stream (in this case the backing store sized is limited to 1000 bytes) to an appropriate value. Use SetPhysicalEndOfStream.

    chunkyStream.SetPhysicalEndOfStream(chunkyStream.GetChunkSize());

Note that you can get the chunk size of the underlying chunky memory without referring to the instance of THeapChunkyMemory directly. You should also set the freeze level of the stream

    chunkyStream.SetFreezeLevel(kSameTeame);

See the section on freeze levels later in this chapter for details an arguments passed to SetFreezeLevel. You can now use chunkyStream to stream out objects. For example, given a pointer to an object, you can now flatten the object as follows.

    aPointer >>= chunkyStream;

This works regardless of whether aPointer points to a standard data a type (int, char, float), an instance of a class (TCollectibleLong, TStandardText), or a collection (TSetOf, TArrayOf, TDictionaryOf).

Resurrecting a stream

Later aPointer can be restored to point to an object identical to the one flattened to chunkyStream.

      chunkyStream.Seek(0);
      aPointer =<< chunkyStream;

Retrieving stream positions

The following code shows protocols for retrieving the positions for logical end-of- stream, physical end-of-stream and current position maintained by stream objects.

      StreamPosition      logicalEnd, physicalEnd, currentPosition;
  
      logicalEnd = chunkyStream.GetLogicalEndOfStream();
      physicalEnd = chunkyStream.GetPhysicalEndOfStream();
      currentPosition = chunkyStream.GetPosition();

Normally, you don't need to know much about this protocol unless you are writing a subclass of TStream and you have to write code to stream out objects in a special format. Even when you do subclass TStream, you don't often have to define special case operations for FlattenPointer or Resurrect because knowledge of how to stream out all primitive data types, as well as MCollectible classes, is embedded in TStream. Usually if you need to work with stream protocol it will be to improve performance and efficiency for a particular class of objects. SeekRelative takes an instance of StreamPositionDelta as an argument as shown in the following code fragment.

      StreamPositionDelta deltaPosition;
  
      deltaPosition = currentPosition + 10;
      chunkyStream.SeekRelative(deltaPosition);

This covers most of the random access protocol inherited from TRandomAccessStream.

Protocol is defined to copy a stream through a constructor.

    TChunkyStream chunkyStreamClone(chunkyStream);

You can also make a copy a a stream using assignment (operator=).

      TChunkyStream       chunkyStreamEqual;
      chunkyStreamEqual = chunkyStream;

[Contents] [Previous] [Next]

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

Generated with WebMaker