Contains stream classes to provide copy-on-write functionality

This unit contains various streams that are used to provide copy-on-write mechanism for TAbstractResource.RawData, via more levels of indirection.

Main class is , which is the stream used for TAbstractResource.RawData. This class uses an underlying stream, to which it redirects operations.

At a lower level, a descendant provides a layer between the original stream and the .

Base cached stream class

This abstract class provides basic cached stream functionalities.

A cached stream is a read-only stream that operates on a portion of another stream. That is, it creates a "window" on the original stream from which to read data. Since it is a read-only stream, trying to write to the stream or to set its size cause an EInvalidOperation exception to be raised.

This class is used by to access the raw data of a resource. When an attempt to write to the stream is detected, replaces it with a memory stream and copies the contents of the cached stream to the memory one, thus providing a copy-on-write mechanism.

An object of this class should never be directly instantiated: use a descendant class instead. The original stream

This protected member is provided to let descendant classes access the original stream.

The size of the cached stream

This protected member is provided to let descendant classes access the size of the cached stream.

The position from the cached stream perspective

This protected member is provided to let descendant classes access the position of the cached stream.

Creates a new object

A new cached stream is created on top of the aStream stream.

The stream from which to read data The resource whose data must be read The size of the resource data An implementation of a cached stream

This class provides an implementation of .

Usually resource readers create a with a TCachedResourceDataStream as the underlying stream.

Cached stream metaclass The type of the underlying stream of TResourceDataStream The underlying stream is a TCachedResourceDataStream descendant The underlying stream is a memory stream The underlying stream is a custom stream Stream class that provides copy-on-write functionality

This class provides the copy-on-write mechanism of TAbstractResource.RawData, via more levels of indirection.

It uses an underlying stream, to which it redirects operations.

The underlying stream can be a descendant, a memory stream or a custom stream. Usually when a resource is loaded from a stream, the underlying stream is a descendant, which provides a read-only stream-like interface over a portion of the original stream (that is, the part of the original stream where resource data resides). When is requested to write data, it replaces the underlying stream with a memory stream, whose contents are copied from the previous underlying stream: this way, copy-on-write functionality can be achieved.

As said before, third possibility is to have a custom stream as the underlying stream: a user can set this stream via TAbstractResource.SetCustomRawDataStream method, which in turn calls

Figure: Levels of indirection

.
                     TResourceDataStream
                              |
       _______________________|_______________________________
      |                       |                               |
TMemoryStream     TCachedDataStream descendant          custom stream
                         /           \
 _______________________|_____________|______________________________
|                o r i g|i n a l   s t|r e a m                       |
|_______________________|_____________|______________________________|

Creates a new object

A new object is created.

If aStream is nil, the underlying stream is a memory stream. Otherwise, a cached stream of the class specified in aClass is created and set as the underlying stream.

The stream which resource data must be read from. It can be nil The resource whose data must be read The size of the resource data The class to use to create the underlying cached stream Compares the stream to another one

This methods compares the stream with aStream. If they are of the same length and their contents are the same, true is returned, false otherwise.

TAbstractResource.CompareContents True if the contents of the two streams are the same The stream to compare to this one. It can be nil Sets a custom stream as the underlying stream

This method sets a custom stream as the underlying stream.

If aStream is nil, a new memory stream is used as the underlying stream. This can be used to remove a previously set custom stream as the underlying stream.

Usually it is called by TAbstractResource.SetCustomRawDataStream.

TAbstractResource.SetCustomRawDataStream The stream to use as the underlying stream. It can be nil Controls the copy-on-write behaviour of the stream

When this property is set to true, a cached stream is used as the underlying stream for read operations. If it is set to false, no caching is performed and data is always copied to a memory stream.

Note that this property does nothing if the underlying stream is a custom stream.

By default this property is true.

TAbstractResource.CacheData