tStream.h

Public Enumerations

EAsyncIOStatus {
  ASYNC_IO_Pending 
  ASYNC_IO_Complete 
  ASYNC_IO_Error 
}

Public Enumerations

EAsyncIOStatus

Enumerator

ASYNC_IO_Pending

I/O is still in queue or being processed.

ASYNC_IO_Complete

I/O has completed successfully.

ASYNC_IO_Error

I/O has aborted with an error.

Status of an asynchronous I/O operation.

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _TSTREAM_H_
 25#define _TSTREAM_H_
 26
 27#ifndef _PLATFORM_H_
 28   #include "platform/platform.h"
 29#endif
 30#ifndef _TYPETRAITS_H_
 31   #include "platform/typetraits.h"
 32#endif
 33
 34
 35//TODO: error handling
 36
 37
 38/// @file
 39/// Definitions for lightweight componentized streaming.
 40///
 41/// This file is an assembly of lightweight classes/interfaces that
 42/// describe various aspects of streaming classes.  The advantage
 43/// over using Torque's Stream class is that very little requirements
 44/// are placed on implementations, that specific abilities can be
 45/// mixed and matched very selectively, and that complex stream processing
 46/// chains can be hidden behind very simple stream interfaces.
 47
 48
 49
 50/// Status of an asynchronous I/O operation.
 51enum EAsyncIOStatus
 52{
 53   ASYNC_IO_Pending,       ///< I/O is still in queue or being processed.
 54   ASYNC_IO_Complete,      ///< I/O has completed successfully.
 55   ASYNC_IO_Error          ///< I/O has aborted with an error.
 56};
 57
 58//-----------------------------------------------------------------------------
 59//    Several component interfaces.
 60//-----------------------------------------------------------------------------
 61
 62/// Interface for streams with an explicit position property.
 63template< typename P = U32 >
 64class IPositionable
 65{
 66   public:
 67   
 68      typedef void Parent;
 69
 70      /// The type used to indicate positions.
 71      typedef P PositionType;
 72
 73      /// @return the current position.
 74      virtual PositionType getPosition() const = 0;
 75      
 76      /// Set the current position to be "pos".
 77      /// @param pos The new position.
 78      virtual void setPosition( PositionType pos ) = 0;
 79};
 80
 81/// Interface for structures that allow their state to be reset.
 82class IResettable
 83{
 84   public:
 85   
 86      typedef void Parent;
 87   
 88      /// Reset to the initial state.
 89      virtual void reset() = 0;
 90};
 91
 92/// Interface for structures of finite size.
 93template< typename T = U32 >
 94class ISizeable
 95{
 96   public:
 97   
 98      typedef void Parent;
 99
100      /// The type used to indicate the structure's size.
101      typedef T SizeType;
102
103      /// @return the size of the structure in number of elements.
104      virtual SizeType getSize() const = 0;
105};
106
107/// Interface for structures that represent processes.
108class IProcess
109{
110   public:
111   
112      typedef void Parent;
113
114      /// Start the process.
115      virtual void start() = 0;
116
117      /// Stop the process.
118      virtual void stop() = 0;
119
120      /// Pause the process.
121      virtual void pause() = 0;
122};
123
124/// Interface for objects that need continuous explicit updates from
125/// an outside source.
126class IPolled
127{
128   public:
129
130      typedef void Parent;
131   
132      /// Update the object state.
133      virtual bool update() = 0;
134};
135
136
137//-----------------------------------------------------------------------------
138//    IInputStream.
139//-----------------------------------------------------------------------------
140
141/// An input stream delivers a sequence of elements of type "T".
142///
143/// @note This stream has an inherent position property and is thus not
144///   safe for concurrent access.
145template< typename T >
146class IInputStream
147{
148   public:
149
150      typedef void Parent;
151
152      /// The element type of this input stream.
153      typedef T ElementType;
154      
155      /// Read the next "num" elements into "buffer".
156      ///
157      /// @param buffer The buffer into which the elements are stored.
158      /// @param num Number of elements to read.
159      /// @return the number of elements actually read; this may be less than
160      ///   "num" or even zero if no elements are available or reading failed.
161      virtual U32 read( ElementType* buffer, U32 num ) = 0;
162};
163
164/// An input stream over elements of type "T" that reads from
165/// user-specified explicit offsets.
166template< typename T, typename Offset = U32 >
167class IOffsetInputStream
168{
169   public:
170
171      typedef void Parent;
172      typedef Offset OffsetType;
173      typedef T ElementType;
174
175      /// Read the next "num" elements at "offset" into "buffer".
176      ///
177      /// @param offset The offset in the stream from which to read.
178      /// @param buffer The buffer into which the elements are stored.
179      /// @param num Number of elements to read.
180      /// @return the number of elements actually read; this may be less than
181      ///   "num" or even zero if no elements are available or reading failed.
182      virtual U32 readAt( OffsetType offset, T* buffer, U32 num ) = 0;
183};
184
185/// An input stream over elements of type "T" that works in
186/// the background.
187template< typename T, typename Offset = U32 >
188class IAsyncInputStream
189{
190   public:
191
192      typedef void Parent;
193      typedef Offset OffsetType;
194      typedef T ElementType;
195
196      /// Queue a read of "num" elements at "offset" into "buffer".
197      ///
198      /// @param offset The offset in the stream from which to read.
199      /// @param buffer The buffer into which the elements are stored.
200      /// @param num Number of elements to read.
201      /// @return a handle for the asynchronous read operation or NULL if the
202      ///   operation could not be queued.
203      virtual void* issueReadAt( OffsetType offset, T* buffer, U32 num ) = 0;
204
205      /// Try moving the given asynchronous read operation to ASYNC_IO_Complete.
206      ///
207      /// @note This method invalidates the given handle.
208      ///
209      /// @param handle Handle returned by "issueReadAt".
210      /// @param outNumRead Reference that receives the number of bytes actually read in the
211      ///   operation.
212      /// @param wait If true, the method waits until the given operation either fails or
213      ///   completes successfully before returning.
214      /// @return the final operation status.
215      virtual EAsyncIOStatus tryCompleteReadAt( void* handle, U32& outNumRead, bool wait = false ) = 0;
216
217      /// Cancel the given asynchronous read operation.
218      ///
219      /// @note This method invalidates the given handle.
220      ///
221      /// @param handle Handle returned by "issueReadAt".
222      virtual void cancelReadAt( void* handle ) = 0;
223};
224
225//-----------------------------------------------------------------------------
226//    IOutputStream.
227//-----------------------------------------------------------------------------
228
229/// An output stream that writes elements of type "T".
230///
231/// @note This stream has an inherent position property and is thus not
232///   safe for concurrent access.
233template< typename T >
234class IOutputStream
235{
236   public:
237
238      typedef void Parent;      
239
240      /// The element type of this input stream.
241      typedef T ElementType;
242
243      /// Write "num" elements from "buffer" to the stream at its
244      /// current position.
245      ///
246      /// @param buffer The buffer from which to read elements.
247      /// @param num Number of elements to write.
248      virtual void write( const ElementType* buffer, U32 num ) = 0;
249};
250
251/// An output stream that writes elements of type "T" to a
252/// user-specified explicit offset.
253template< typename T, typename Offset = U32 >
254class IOffsetOutputStream
255{
256   public:
257
258      typedef void Parent;
259      typedef Offset OffsetType;
260      typedef T ElementType;
261
262      /// Write "num" elements from "buffer" to the stream at "offset".
263      ///
264      /// @param offset The offset in the stream at which to write the elements.
265      /// @param buffer The buffer from which to read elements.
266      /// @param num Number of elements to write.
267      virtual void writeAt( OffsetType offset, const ElementType* buffer, U32 num ) = 0;
268};
269
270/// An output stream that writes elements of type "T" in the background.
271template< typename T, typename Offset = U32 >
272class IAsyncOutputStream
273{
274   public:
275
276      typedef void Parent;
277      typedef Offset OffsetType;
278      typedef T ElementType;
279
280      /// Queue a write operation of "num" elements from "buffer" to stream position
281      /// "offset".
282      ///
283      /// @param offset The offset in the stream at which to write the elements.
284      /// @param buffer The buffer from which to read elements.
285      /// @param num The number of elements to write.
286      /// @return a handle to the asynchronous write operatior or NULL if the operation
287      ///   could not be queued.
288      virtual void* issueWriteAt( OffsetType offset, const ElementType* buffer, U32 num ) = 0;
289
290      /// Try moving the given asynchronous write operation to ASYNC_IO_Complete.
291      ///
292      /// @note This method invalidates the given handle.
293      ///
294      /// @param handle Handle returned by "issueWriteAt".
295      /// @param wait If true, the method waits until the given operation either fails or
296      ///   completes successfully before returning.
297      /// @return the final operation status.
298      virtual EAsyncIOStatus tryCompleteWriteAt( void* handle, bool wait = false ) = 0;
299
300      /// Cancel the given asynchronous write operation.
301      ///
302      /// @note This method invalidates the given handle.
303      ///
304      /// @param handle Handle return by "issueWriteAt".
305      virtual void cancelWriteAt( void* handle ) = 0;
306};
307
308//-----------------------------------------------------------------------------
309//    IInputStreamFilter.
310//-----------------------------------------------------------------------------
311
312/// An input stream filter takes an input stream "Stream" and processes it
313/// into an input stream over type "To".
314template< typename To, typename Stream >
315class IInputStreamFilter : public IInputStream< To >
316{
317   public:
318
319      typedef IInputStream< To> Parent;
320
321      ///
322      typedef typename TypeTraits< Stream >::BaseType SourceStreamType;
323
324      /// The element type of the source stream.
325      typedef typename SourceStreamType::ElementType SourceElementType;
326
327      /// Construct a filter reading elements from "stream".
328      IInputStreamFilter( const Stream& stream )
329         : mSourceStream( stream ) {}
330
331      /// Return the stream from which this filter is reading its
332      /// source elements.
333      const Stream& getSourceStream() const { return mSourceStream; }
334      Stream& getSourceStream() { return mSourceStream; }
335
336   private:
337
338      Stream mSourceStream;
339};
340
341//-----------------------------------------------------------------------------
342//    IOutputStreamFilter.
343//-----------------------------------------------------------------------------
344
345/// An output stream filter takes an output stream "Stream" and processes it
346/// into an output stream over type "To".
347template< typename To, class Stream >
348class IOutputStreamFilter : public IOutputStream< To >
349{
350   public:
351
352      typedef IOutputStream< To> Parent;
353
354      ///
355      typedef typename TypeTraits< Stream >::BaseType TargetStreamType;
356
357      /// The element type of the target stream.
358      typedef typename TargetStreamType::ElementType TargetElementType;
359
360      /// Construct a filter writing elements to "stream".
361      IOutputStreamFilter( const Stream& stream )
362         : mTargetStream( stream ) {}
363
364      /// Return the stream to which this filter is writing its
365      /// elements.
366      const Stream& getTargetStream() const { return mTargetStream; }
367      Stream& getTargetStream() { return mTargetStream; }
368
369   private:
370
371      Stream mTargetStream;
372};
373
374#endif // _TSTREAM_H_
375