include/ptclib/delaychan.h

   1 /*
   2  * delaychan.h
   3  *
   4  * Class for implementing a serial queue channel in memory.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 2001 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Contributor(s): ______________________________________.
  25  *
  26  * $Log$
  27  * Revision 1.4  2002/09/16 01:08:59  robertj
  28  * Added #define so can select if #pragma interface/implementation is used on
  29  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  30  *
  31  * Revision 1.3  2002/02/25 11:05:02  rogerh
  32  * New Delay code which solves the accumulated error problem. Based on ideas
  33  * by Tomasz Motylewski <T.Motylewski@bfad.de>, Roger and Craig.
  34  *
  35  * Revision 1.2  2002/01/15 03:55:43  craigs
  36  * Added PAdaptiveDelay class
  37  *
  38  * Revision 1.1  2001/07/10 03:07:07  robertj
  39  * Added queue channel and delay channel classes to ptclib.
  40  *
  41  */
  42
  43 #ifndef _DELAYCHAN_H
  44 #define _DELAYCHAN_H
  45
  46
  47 #ifdef P_USE_PRAGMA
  48 #pragma interface
  49 #endif
  50
  51 /** Class for implementing an "adaptive" delay.
  52     This class will cause the the caller to, on average, delay
  53     the specified number of milliseconds between calls. This can
  54     be used to simulate hardware timing for a sofwtare only device
  55
  56   */
  57
  58
  59 class PAdaptiveDelay : public PObject
  60 {
  61   PCLASSINFO(PAdaptiveDelay, PObject);
  62
  63   public:
  64     PAdaptiveDelay();
  65     BOOL Delay(int time);
  66     void Restart();
  67
  68   protected:
  69     BOOL   firstTime;
  70     PTime  targetTime;
  71 };
  72
  73
  74 /** Class for implementing a "delay line" channel.
  75     This indirect channel can be placed in a channel I/O chain to limit the
  76     speed of I/O. This can be useful if blocking is not available and buffers
  77     could be overwritten if the I/O occurs at full speed.
  78
  79     There are two modes of operation. In stream more, data can be read/written
  80     no faster than a fixed time for a fixed number of bytes. So, for example,
  81     you can say than 320 bytes must take 20 milliseconds, and thus if the
  82     application writes 640 byets it will delay 40 milliseconds before the next
  83     write.
  84
  85     In frame mode, the rate limiting applies to individual read or write
  86     operations. So you can say that each read takes 30 milliseconds even if
  87     on 4 bytes is read, and the same time if 24 bytes are read.
  88   */
  89 class PDelayChannel : public PIndirectChannel
  90 {
  91     PCLASSINFO(PDelayChannel, PIndirectChannel);
  92   public:
  93   /**@name Construction */
  94   //@{
  95     enum Mode {
  96       DelayReadsOnly,
  97       DelayWritesOnly,
  98       DelayReadsAndWrites
  99     };
 100
 101     /** Create a new delay channel with the specified delays. A value of zero
 102         for the numBytes parameter indicates that the delay is in frame mode.
 103
 104         The maximum skip time is the number of milliseconds that the delay
 105         may "catch up" by using zero delays. This is caused by the Read() or
 106         Write() not being called for a time by external factors.
 107       */
 108     PDelayChannel(
 109       Mode mode,                  /// Mode for delay channel
 110       unsigned frameDelay,        /// Delay time in milliseconds
 111       PINDEX frameSize = 0,       /// Bytes to apply to the delay time.
 112       unsigned maximumSlip = 250, /// Maximum slip time in milliseconds
 113       unsigned minimumDelay = 10  /// Minimim delay (usually OS time slice)
 114     );
 115   //@}
 116
 117
 118   /**@name Overrides from class PChannel */
 119   //@{
 120     /**Low level read from the file channel. The read timeout is ignored for
 121        file I/O. The GetLastReadCount() function returns the actual number
 122        of bytes read.
 123
 124        The GetErrorCode() function should be consulted after Read() returns
 125        FALSE to determine what caused the failure.
 126
 127        @return
 128        TRUE indicates that at least one character was read from the channel.
 129        FALSE means no bytes were read due to timeout or some other I/O error.
 130      */
 131     virtual BOOL Read(
 132       void * buf,   /// Pointer to a block of memory to receive the read bytes.
 133       PINDEX len    /// Maximum number of bytes to read into the buffer.
 134     );
 135
 136     /**Low level write to the file channel. The write timeout is ignored for
 137        file I/O. The GetLastWriteCount() function returns the actual number
 138        of bytes written.
 139
 140        The GetErrorCode() function should be consulted after Write() returns
 141        FALSE to determine what caused the failure.
 142
 143        @return TRUE if at least len bytes were written to the channel.
 144      */
 145     virtual BOOL Write(
 146       const void * buf, /// Pointer to a block of memory to write.
 147       PINDEX len        /// Number of bytes to write.
 148     );
 149   //@}
 150
 151
 152   protected:
 153     virtual void Wait(PINDEX count, PTimeInterval & nextTick);
 154
 155     Mode          mode;
 156     unsigned      frameDelay;
 157     PINDEX        frameSize;
 158     PTimeInterval maximumSlip;
 159     PTimeInterval minimumDelay;
 160
 161     PTimeInterval nextReadTick;
 162     PTimeInterval nextWriteTick;
 163 };
 164
 165
 166 #endif // _DELAYCHAN_H
 167
 168
 169 // End Of File ///////////////////////////////////////////////////////////////