 |
Vault
4.1
|
|
Vault
4.1
|
Modules | |
| Formatted Streams (upper layer) | |
These are the stream classes that you use to read and write formatted data -- either text- or binary-oriented data -- regardless of what transport it is carried over. | |
| Raw Streams (lower layer) | |
These are the stream classes that you use to specify what sort of physical transport the stream data is carried over -- file, socket, or memory. | |
| Stream Utilities | |
These are the utility classes related to streams. | |
The stream facilities provided by the Vault are extremely easy to use, and provide a clean and simple architecture for stream i/o. There are two layers in the stream architecture. Usually you will talk to the upper layer, even if you have to instantiate lowerx layer objects to set up the stream.
The lower layer concerns the transport over which the stream is carried. The Vault supplies implementations for files, sockets, and memory. The base class is VStream, and its primary function is to read and write bytes, to seek (as allowed), and to flush. The concrete subclasses provide the actual i/o implementation that works over the particular transport. Data at this stream layer is untyped -- it's all just bytes. You'll instantiate either a VBufferedFileStream, VDirectIOFileStream, VSocketStream, or VMemoryStream, either directly or indirectly. In addition, the class VWriteBufferedStream lets you buffer writes to a stream such as VSocketStream that doesn't buffer data on its own. VMemoryStream uses a memory buffer to hold the stream data; you don't have to worry about writing past the end of the buffer: it expands as necessary. Regarding VBufferedFileStream vs. VDirectIOFileStream, you should generally use VBufferedFileStream, unless you need the particular behavior of VDirectIOFileStream, because VBufferedFileStream uses the platform APIs that give better file i/o performance.
The upper layer is the one you will most often use directly. This layer concerns the format of the data stream, independent of the lower layer transport that the stream is carried over. The Vault supplies implementations for binary i/o and text/line-based i/o. You'll instantiate either a VBinaryIOStream or VTextIOStream and associate with a lower layer stream object (discussed above), and then you'll use the upper layer stream object's APIs for reading and writing data in the appropriate format. For example, with binary i/o, you read and write typed data such as: integers of particular sizes; floating-point values; booleans; strings; time values (instants). In contrast, with text i/o, you read and write lines of text as strings; the text i/o class manages the details of how text file line endings differ across platforms, and the fact that you might be reading a file on one platform that was created on a different platform.
Copying between streams is made trivial by the overloaded streamCopy methods of VStream and VIOStream. These methods allow you to copy data from one stream to another regardless of the type of stream, and regardless of whether you have a reference to a lower layer VStream object or an upper layer VIOStream object. The implementation ensures that no extra copying is performed -- if you are doing i/o where one stream (source or destination) is a file or socket, and the other stream is a memory buffer, the copying is done directly to/from the buffer with zero overhead. Yet you can supply a pair of non-memory-based streams (file and socket) and a temporary buffer will be used to perform the copy without requiring you to deal with the details (although you may specify the buffer size explicitly if the default size is not ideal).
The semantics of stream copying are simple: the source is read and the destination is written. So the stream position moves as you'd expect. If you need to copy without performing the entire copy in a single blocking function call, you can use the helper class VStreamCopier, which allows you to copy in chunks and thus be aware of the progress of the copy; an example of where this is useful is if you are copying a large amount of data and need to keep some UI feedback updated as the copy progresses.