include/ptlib/semaphor.h

   1 /*
   2  * semaphor.h
   3  *
   4  * Thread synchronisation semaphore class.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 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  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.22  2007/09/05 11:58:47  csoutheren
  31  * Fixed build on MacOSX
  32  *
  33  * Revision 1.21  2005/11/25 03:43:47  csoutheren
  34  * Fixed function argument comments to be compatible with Doxygen
  35  *
  36  * Revision 1.20  2005/11/14 22:29:13  csoutheren
  37  * Reverted Wait and Signal to non-const - there is no way we can guarantee that all
  38  * descendant classes everywhere will be changed over, so we have to keep the
  39  * original  API
  40  *
  41  * Revision 1.19  2005/11/04 06:34:20  csoutheren
  42  * Added new class PSync as abstract base class for all mutex/sempahore classes
  43  * Changed PCriticalSection to use Wait/Signal rather than Enter/Leave
  44  * Changed Wait/Signal to be const member functions
  45  * Renamed PMutex to PTimedMutex and made PMutex synonym for PCriticalSection.
  46  * This allows use of very efficient mutex primitives in 99% of cases where timed waits
  47  * are not needed
  48  *
  49  * Revision 1.18  2003/09/17 05:41:59  csoutheren
  50  * Removed recursive includes
  51  *
  52  * Revision 1.17  2003/09/17 01:18:02  csoutheren
  53  * Removed recursive include file system and removed all references
  54  * to deprecated coooperative threading support
  55  *
  56  * Revision 1.16  2002/09/16 01:08:59  robertj
  57  * Added #define so can select if #pragma interface/implementation is used on
  58  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  59  *
  60  * Revision 1.15  2002/01/23 04:26:36  craigs
  61  * Added copy constructors for PSemaphore, PMutex and PSyncPoint to allow
  62  * use of default copy constructors for objects containing instances of
  63  * these classes
  64  *
  65  * Revision 1.14  2001/11/23 00:55:18  robertj
  66  * Changed PWaitAndSignal so works inside const functions.
  67  *
  68  * Revision 1.13  2001/06/01 04:00:21  yurik
  69  * Removed dependency on obsolete function
  70  *
  71  * Revision 1.12  2001/05/22 12:49:32  robertj
  72  * Did some seriously wierd rewrite of platform headers to eliminate the
  73  *   stupid GNU compiler warning about braces not matching.
  74  *
  75  * Revision 1.11  2001/04/23 00:34:29  robertj
  76  * Added ability for PWaitAndSignal to not wait on semaphore.
  77  *
  78  * Revision 1.10  2001/01/27 23:40:09  yurik
  79  * WinCE port-related - CreateEvent used instead of CreateSemaphore
  80  *
  81  * Revision 1.9  2000/12/19 22:20:26  dereks
  82  * Add video channel classes to connect to the PwLib PVideoInputDevice class.
  83  * Add PFakeVideoInput class to generate test images for video.
  84  *
  85  * Revision 1.8  1999/03/09 02:59:50  robertj
  86  * Changed comments to doc++ compatible documentation.
  87  *
  88  * Revision 1.7  1999/02/16 08:11:10  robertj
  89  * MSVC 6.0 compatibility changes.
  90  *
  91  * Revision 1.6  1998/11/19 05:17:37  robertj
  92  * Added PWaitAndSignal class for easier mutexing.
  93  *
  94  * Revision 1.5  1998/09/23 06:21:19  robertj
  95  * Added open source copyright license.
  96  *
  97  * Revision 1.4  1998/03/20 03:16:11  robertj
  98  * Added special classes for specific sepahores, PMutex and PSyncPoint.
  99  *
 100  * Revision 1.3  1995/12/10 11:34:50  robertj
 101  * Fixed incorrect order of parameters in semaphore constructor.
 102  *
 103  * Revision 1.2  1995/11/21 11:49:42  robertj
 104  * Added timeout on semaphore wait.
 105  *
 106  * Revision 1.1  1995/08/01 21:41:24  robertj
 107  * Initial revision
 108  *
 109  */
 110
 111 #ifndef _PSEMAPHORE
 112 #define _PSEMAPHORE
 113
 114 #ifdef P_USE_PRAGMA
 115 #pragma interface
 116 #endif
 117
 118 #include <ptlib/psync.h>
 119 #include <limits.h>
 120 #include <ptlib/critsec.h>
 121
 122 /**This class defines a thread synchonisation object. This is in the form of a
 123    integer semaphore. The semaphore has a count and a maximum value. The
 124    various combinations of count and usage of the #Wait()# and
 125    #Signal()# functions determine the type of synchronisation mechanism
 126    to be employed.
 127
 128    The #Wait()# operation is that if the semaphore count is > 0,
 129    decrement the semaphore and return. If it is = 0 then wait (block).
 130
 131    The #Signal()# operation is that if there are waiting threads then
 132    unblock the first one that was blocked. If no waiting threads and the count
 133    is less than the maximum then increment the semaphore.
 134
 135    The most common is to create a mutual exclusion zone. A mutex is where a
 136    piece of code or data cannot be accessed by more than one thread at a time.
 137    To prevent this the PSemaphore is used in the following manner:
 138 \begin{verbatim}
 139       PSemaphore mutex(1, 1);  // Maximum value of 1 and initial value of 1.
 140
 141       ...
 142
 143       mutex.Wait();
 144
 145       ... critical section - only one thread at a time here.
 146
 147       mutex.Signal();
 148
 149       ...
 150 \end{verbatim}
 151     The first thread will pass through the #Wait()# function, a second
 152     thread will block on that function until the first calls the
 153     #Signal()# function, releasing the second thread.
 154  */
 155 class PSemaphore : public PSync
 156 {
 157   PCLASSINFO(PSemaphore, PSync);
 158
 159   public:
 160   /**@name Construction */
 161   //@{
 162     /**Create a new semaphore with maximum count and initial value specified.
 163        If the initial value is larger than the maximum value then is is set to
 164        the maximum value.
 165      */
 166     PSemaphore(
 167       unsigned initial, ///< Initial value for semaphore count.
 168       unsigned maximum  ///< Maximum value for semaphore count.
 169     );
 170
 171     /** Create a new Semaphore with the same initial and maximum values as the original
 172      */
 173     PSemaphore(const PSemaphore &);
 174
 175     /**Destroy the semaphore. This will assert if there are still waiting
 176        threads on the semaphore.
 177      */
 178     ~PSemaphore();
 179   //@}
 180
 181   /**@name Operations */
 182   //@{
 183     /**If the semaphore count is > 0, decrement the semaphore and return. If
 184        if is = 0 then wait (block).
 185      */
 186     virtual void Wait();
 187
 188     /**If the semaphore count is > 0, decrement the semaphore and return. If
 189        if is = 0 then wait (block) for the specified amount of time.
 190
 191        @return
 192        TRUE if semaphore was signalled, FALSE if timed out.
 193      */
 194     virtual BOOL Wait(
 195       const PTimeInterval & timeout // Amount of time to wait for semaphore.
 196     );
 197
 198     /**If there are waiting (blocked) threads then unblock the first one that
 199        was blocked. If no waiting threads and the count is less than the
 200        maximum then increment the semaphore.
 201      */
 202     virtual void Signal();
 203
 204     /**Determine if the semaphore would block if the #Wait()# function
 205        were called.
 206
 207        @return
 208        TRUE if semaphore will block when Wait() is called.
 209      */
 210     virtual BOOL WillBlock() const;
 211   //@}
 212
 213   private:
 214     PSemaphore & operator=(const PSemaphore &) { return *this; }
 215
 216
 217 // Include platform dependent part of class
 218 #ifdef _WIN32
 219 #include "msos/ptlib/semaphor.h"
 220 #else
 221 #include "unix/ptlib/semaphor.h"
 222 #endif
 223 };
 224
 225 #endif
 226
 227 // End Of File ///////////////////////////////////////////////////////////////