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.10  2007/04/18 23:49:50  csoutheren
  28  * Add usage of precompiled headers
  29  *
  30  * Revision 1.9  2006/07/21 01:03:12  csoutheren
  31  * Fixed to PAdaptiveDelay
  32  * Thanks to Paolo Amadini
  33  *
  34  * Revision 1.8  2006/07/19 06:03:34  csoutheren
  35  * Add extension PAdaptiveDelay to set maximum and minimum delay times
  36  * Thanks to Paolo Amadini
  37  *
  38  * Revision 1.7  2006/06/20 12:44:02  csoutheren
  39  * Added new constructor for PDelayChannel
  40  * Thanks to Frederic Heem
  41  *
  42  * Revision 1.6  2005/11/30 12:47:37  csoutheren
  43  * Removed tabs, reformatted some code, and changed tags for Doxygen
  44  *
  45  * Revision 1.5  2004/11/11 07:34:50  csoutheren
  46  * Added #include <ptlib.h>
  47  *
  48  * Revision 1.4  2002/09/16 01:08:59  robertj
  49  * Added #define so can select if #pragma interface/implementation is used on
  50  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  51  *
  52  * Revision 1.3  2002/02/25 11:05:02  rogerh
  53  * New Delay code which solves the accumulated error problem. Based on ideas
  54  * by Tomasz Motylewski <T.Motylewski@bfad.de>, Roger and Craig.
  55  *
  56  * Revision 1.2  2002/01/15 03:55:43  craigs
  57  * Added PAdaptiveDelay class
  58  *
  59  * Revision 1.1  2001/07/10 03:07:07  robertj
  60  * Added queue channel and delay channel classes to ptclib.
  61  *
  62  */
  63
  64 #ifndef _DELAYCHAN_H
  65 #define _DELAYCHAN_H
  66
  67
  68 #ifdef P_USE_PRAGMA
  69 #pragma interface
  70 #endif
  71
  72 #ifndef _PTLIB_H
  73 #include <ptlib.h>
  74 #endif
  75
  76 /** Class for implementing an "adaptive" delay.
  77     This class will cause the the caller to, on average, delay
  78     the specified number of milliseconds between calls. This can
  79     be used to simulate hardware timing for a sofwtare only device
  80
  81   */
  82
  83
  84 class PAdaptiveDelay : public PObject
  85 {
  86   PCLASSINFO(PAdaptiveDelay, PObject);
  87
  88   public:
  89
  90   /**@name Construction */
  91   //@{
  92     /**Create a new adaptive delay with the specified parameters.
  93
  94        The maximum slip time can also be set later using SetMaximumSlip.
  95       */
  96     PAdaptiveDelay(
  97       unsigned maximumSlip = 0,   ///< Maximum slip time in milliseconds
  98       unsigned minimumDelay = 0   ///< Minimum delay (usually OS time slice)
  99     );
 100   //@}
 101
 102   /**@name Operating Parameters */
 103   //@{
 104     /**Set the number of milliseconds that the delay may "catch up" by
 105        using zero delays. This is caused by the Delay() function not
 106        being called for a time by external factors.
 107
 108        If @a maximumSlip is 0, this feature is disabled.
 109       */
 110     void SetMaximumSlip(PTimeInterval maximumSlip)
 111     { jitterLimit = maximumSlip; }
 112
 113     /**Get the current slip time. */
 114     PTimeInterval GetMaximumSlip() const
 115     { return jitterLimit; }
 116   //@}
 117
 118   /**@name Functionality */
 119   //@{
 120     /**Wait until the specified number of milliseconds have elapsed from
 121        the previous call (on average). The first time the function is called,
 122        no delay occurs. If the maximum slip time is set and the caller
 123        is "too late", the timer is restarted automatically and no delay
 124        occurs.
 125
 126        If the calculated delay is less than the OS timer resolution
 127        specified on costruction, no delay occurs now ("better sooner
 128        than later" strategy).
 129
 130        @return
 131        TRUE if we are "too late" of @a time milliseconds (unrelated to
 132        the maximum slip time).
 133       */
 134     BOOL Delay(int time);
 135
 136     /**Invalidate the timer. The timing of this function call is not
 137        important, the timer will restart at the next call to Delay().
 138       */
 139     void Restart();
 140   //@}
 141
 142   protected:
 143     BOOL   firstTime;
 144     PTime  targetTime;
 145
 146     PTimeInterval  jitterLimit;
 147     PTimeInterval  minimumDelay;
 148 };
 149
 150
 151 /** Class for implementing a "delay line" channel.
 152     This indirect channel can be placed in a channel I/O chain to limit the
 153     speed of I/O. This can be useful if blocking is not available and buffers
 154     could be overwritten if the I/O occurs at full speed.
 155
 156     There are two modes of operation. In stream more, data can be read/written
 157     no faster than a fixed time for a fixed number of bytes. So, for example,
 158     you can say than 320 bytes must take 20 milliseconds, and thus if the
 159     application writes 640 byets it will delay 40 milliseconds before the next
 160     write.
 161
 162     In frame mode, the rate limiting applies to individual read or write
 163     operations. So you can say that each read takes 30 milliseconds even if
 164     on 4 bytes is read, and the same time if 24 bytes are read.
 165   */
 166 class PDelayChannel : public PIndirectChannel
 167 {
 168     PCLASSINFO(PDelayChannel, PIndirectChannel);
 169   public:
 170   /**@name Construction */
 171   //@{
 172     enum Mode {
 173       DelayReadsOnly,
 174       DelayWritesOnly,
 175       DelayReadsAndWrites
 176     };
 177
 178     /** Create a new delay channel with the specified delays. A value of zero
 179         for the numBytes parameter indicates that the delay is in frame mode.
 180
 181         The maximum skip time is the number of milliseconds that the delay
 182         may "catch up" by using zero delays. This is caused by the Read() or
 183         Write() not being called for a time by external factors.
 184       */
 185     PDelayChannel(
 186       Mode mode,                  ///< Mode for delay channel
 187       unsigned frameDelay,        ///< Delay time in milliseconds
 188       PINDEX frameSize = 0,       ///< Bytes to apply to the delay time.
 189       unsigned maximumSlip = 250, ///< Maximum slip time in milliseconds
 190       unsigned minimumDelay = 10  ///< Minimim delay (usually OS time slice)
 191     );
 192
 193     /** Create a new delay channel with the specified delays and channel. A value of zero
 194     for the numBytes parameter indicates that the delay is in frame mode.
 195
 196     The maximum skip time is the number of milliseconds that the delay
 197     may "catch up" by using zero delays. This is caused by the Read() or
 198     Write() not being called for a time by external factors.
 199      */
 200     PDelayChannel(
 201         PChannel &channel,          ///< channel to use
 202         Mode mode,                  ///< Mode for delay channel
 203         unsigned frameDelay,        ///< Delay time in milliseconds
 204         PINDEX frameSize = 0,       ///< Bytes to apply to the delay time.
 205         unsigned maximumSlip = 250, ///< Maximum slip time in milliseconds
 206         unsigned minimumDelay = 10  ///< Minimim delay (usually OS time slice)
 207                  );
 208   //@}
 209
 210
 211   /**@name Overrides from class PChannel */
 212   //@{
 213     /**Low level read from the file channel. The read timeout is ignored for
 214        file I/O. The GetLastReadCount() function returns the actual number
 215        of bytes read.
 216
 217        The GetErrorCode() function should be consulted after Read() returns
 218        FALSE to determine what caused the failure.
 219
 220        @return
 221        TRUE indicates that at least one character was read from the channel.
 222        FALSE means no bytes were read due to timeout or some other I/O error.
 223      */
 224     virtual BOOL Read(
 225       void * buf,   ///< Pointer to a block of memory to receive the read bytes.
 226       PINDEX len    ///< Maximum number of bytes to read into the buffer.
 227     );
 228
 229     /**Low level write to the file channel. The write timeout is ignored for
 230        file I/O. The GetLastWriteCount() function returns the actual number
 231        of bytes written.
 232
 233        The GetErrorCode() function should be consulted after Write() returns
 234        FALSE to determine what caused the failure.
 235
 236        @return TRUE if at least len bytes were written to the channel.
 237      */
 238     virtual BOOL Write(
 239       const void * buf, ///< Pointer to a block of memory to write.
 240       PINDEX len        ///< Number of bytes to write.
 241     );
 242   //@}
 243
 244
 245   protected:
 246     virtual void Wait(PINDEX count, PTimeInterval & nextTick);
 247
 248     Mode          mode;
 249     unsigned      frameDelay;
 250     PINDEX        frameSize;
 251     PTimeInterval maximumSlip;
 252     PTimeInterval minimumDelay;
 253
 254     PTimeInterval nextReadTick;
 255     PTimeInterval nextWriteTick;
 256 };
 257
 258
 259 #endif // _DELAYCHAN_H
 260
 261
 262 // End Of File ///////////////////////////////////////////////////////////////