About Stream
(some loosely organized comments about Stream by Konstantin Hartwich)
Stream represents only a logical 'cut out piece' or a finite snapshot of a per definition concurrent, infinite data stream, beeing processed, handled or available to some extent. hence the pos variable, it it is indicating the current offset or pos'ition of the data chunk represented by your Stream instance, from the logical start or beginning of stream.
Stream is basicly only an interface class with some pointers to ref some memory space somewhere. it usually does not contain (own in U++ terms) the data itself. Thats why it may have MemStream, StringStream, FileStream etc.. 'they' access or even contain (StringBuffer) the buffer and are using the pointers from Stream base to handle it. The buffer referenced by Stream is a current chunk of data, *entirely* accessable in your stream.
Stream is unidirectional per definition and should be used as such. In contrast to other Stream implementations, Upp Stream brings in all to be used both as Input or as Output stream. these 2 modes are supported in one single instance, but should't be used at same time. Nevertheless, it does not produce ASSERT, Exception or errror messages if one tries to Put and Get stuff from same Stream, it simply might not be logical or what you expect or want, because Stream uses only one ptr to represent current 'head' position for reading or writing. (thus it is not intrinsically possible to use a MemStream as a Circular Buffer, which would be nice. (btw, how about implementing such one?) These 2 Modes can be differed using the API functions IsStoring() / IsLoading(). The Modes are set using SetStoring() / SetLoading() and are normally set automatically, depending on how you created the stream instance.
in both modes, the extension of the buffer marks the accessible space for *entire* reading or writing, using rdlim and wrlim pointers. for reading, it means the current available, readable data chunk. For writing, it means the *already allocated* data for beeing able to write to. When reading, ptr meaning the curent read position. buffer to ptr is data already processed by read. the space from ptr till rdlim meaning the still to read data. When writing, buffer till ptr meaning the data, already written to the space, ptr till wrlim the space free to fill (before a Flush should be triggered, if supported, or is triggered automatically, ie. FileStream)
Serializing stuff to Stream is quite cool. in other implementations, Stream has a split interface for serializing and deserializing stuff, so the user had to keep track which order the elements go and use 2 different functions basicly, for Serializing and Deserializing. upp stream puts away this head ache. it uses 1 interface, and handles the difference about serialize/deserialize internally & implicitly with the help of IsLoading() / IsStoring()..the user benefits from this only having to specify *one* functionional place, that determines the order of serialization and that is maintained the same on both directions, hurray. (drawback, one cant deserialize from a 'const Stream &', because the function needs a 'Stream &', but the case where this happens is to be neglacted). since this is somehow unusual, one needs to get familiar with the Stream.
A global template operator%(Stream &, T &) enables your class to be serialized as well by the user, simply calling stream % yourclass. to make this happen, provide a 'void Serialize(Stream& s)' function in your class, where you define the the behaviour and order of de/serialization of your content (other data types also beeing serializable). after deserializing your class, finishing init of your class should be done. this makes handling of data transport using Socket quite easy, but is not yet implemented Smile
You can easily implement own buffered Streams, it provides a mainly protected interface. Stream provides a rich default serialization interface to serialize all kind of stuff, including NTL containers...(recursively calling serialize on them then as well..)
One should know pretty well what kind of Stream to use what for.. i.e. a MemStream cant be used as a self growing Buffer, it handles only a previously provided chunk of memory which cant grow just like that (because the memory chunk cant grow). for this purpose, use StringStream.
The basic implementation of a Stream is this: a Stream refers to a chunk of memory, represented by 'buffer' pointer. it implicitly stores its size with the rdlim and wrlim pointers, representing the extension of the buffer for reading and writing operations. every API function asumes that it can store or read its data directly in this chunk of data, at ptr location, normally whitout invoking any kind of flush or the like, advancing the ptr though. But sooner or later it will have consumed it's space (reacing respective rdlim, means having read all, or wrlim, meaning having written all). then it will claim some 'upper level' action to either provide more data, done by advanceing the snapshot position in the read case, or writing out stored data and mark it as free again. this is done invoking _Get(..) or _Put(..). in other words... _Put normally should take care of processing the full buffer by flushing it somehow, process the data provided, that didnt fit in the full buffer, and rewinding the ptr and adjusting wrlim, declaring buffer empty. _Get typically claims some more data to be made available inside the Stream, maybe by copying some data in provided empty buffer first, then remainder in buffer and again rewinding the ptr and adjusting rdlim. this behaviour is to be defined somehow, and is special for any kind of stream.
Flushing behavior is only used for write side, or out buffers. it is not invoked by generic Stream implementation by default. but higher level Streams use it in to do exacely this. flushing queued data to the underying destination (File Streams only so far).
there are several helper functions around handling Streams, even copying, which is normally not possible just like that, or stuff like providing a version for streamed data and some constraints on version (min, max) when serializing. take a look in Stream.cpp.
OutStream uses a small internal buffer to accumulate things, before it forwards them to a to be user implemented Out(..) function, which should take care of processing it somehow (sending somewhere or what ever..)
TeeStream is an OutStream that uses internal buffer again, and when time has come, pushes it to 2 other streams..(so a little 'data latency' is expected..if you want to make the data be available at once, call Flush() after your operations..
|
