include/ptlib/mutex.h

   1 /*
   2  * mutex.h
   3  *
   4  * Mutual exclusion thread synchonisation 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.16  2007/09/05 11:58:47  csoutheren
  31  * Fixed build on MacOSX
  32  *
  33  * Revision 1.15  2007/09/05 11:09:09  csoutheren
  34  * Removed misleading and incorrect code from Linux implementation of
  35  * PCriticalSection. Apologies to Hannes Friederich :(
  36  *
  37  * Revision 1.14  2005/11/25 00:06:12  csoutheren
  38  * Applied patch #1364593 from Hannes Friederich
  39  * Also changed so PTimesMutex is no longer descended from PSemaphore on
  40  * non-Windows platforms
  41  *
  42  * Revision 1.13  2005/11/08 22:31:00  csoutheren
  43  * Moved declaration of PMutex
  44  *
  45  * Revision 1.12  2005/11/08 22:18:31  csoutheren
  46  * Changed PMutex to use PTimedMutex on non-Windows platforms because
  47  * sem_wait is not recursive. Very sad.
  48  * Thanks to Frederic Heem for finding this problem
  49  *
  50  * Revision 1.11  2005/11/04 06:34:20  csoutheren
  51  * Added new class PSync as abstract base class for all mutex/sempahore classes
  52  * Changed PCriticalSection to use Wait/Signal rather than Enter/Leave
  53  * Changed Wait/Signal to be const member functions
  54  * Renamed PMutex to PTimedMutex and made PMutex synonym for PCriticalSection.
  55  * This allows use of very efficient mutex primitives in 99% of cases where timed waits
  56  * are not needed
  57  *
  58  * Revision 1.10  2003/09/17 05:41:58  csoutheren
  59  * Removed recursive includes
  60  *
  61  * Revision 1.9  2003/09/17 01:18:02  csoutheren
  62  * Removed recursive include file system and removed all references
  63  * to deprecated coooperative threading support
  64  *
  65  * Revision 1.8  2002/09/16 01:08:59  robertj
  66  * Added #define so can select if #pragma interface/implementation is used on
  67  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  68  *
  69  * Revision 1.7  2002/01/23 04:26:36  craigs
  70  * Added copy constructors for PSemaphore, PMutex and PSyncPoint to allow
  71  * use of default copy constructors for objects containing instances of
  72  * these classes
  73  *
  74  * Revision 1.6  2001/05/22 12:49:32  robertj
  75  * Did some seriously wierd rewrite of platform headers to eliminate the
  76  *   stupid GNU compiler warning about braces not matching.
  77  *
  78  * Revision 1.5  1999/03/09 02:59:50  robertj
  79  * Changed comments to doc++ compatible documentation.
  80  *
  81  * Revision 1.4  1999/02/16 08:12:22  robertj
  82  * MSVC 6.0 compatibility changes.
  83  *
  84  * Revision 1.3  1998/11/30 02:50:59  robertj
  85  * New directory structure
  86  *
  87  * Revision 1.2  1998/09/23 06:20:55  robertj
  88  * Added open source copyright license.
  89  *
  90  * Revision 1.1  1998/03/23 02:41:31  robertj
  91  * Initial revision
  92  *
  93  */
  94
  95 #ifndef _PMUTEX
  96 #define _PMUTEX
  97
  98 #ifdef P_USE_PRAGMA
  99 #pragma interface
 100 #endif
 101
 102 #include <ptlib/critsec.h>
 103 #include <ptlib/semaphor.h>
 104
 105 /**This class defines a thread mutual exclusion object. A mutex is where a
 106    piece of code or data cannot be accessed by more than one thread at a time.
 107    To prevent this the PMutex is used in the following manner:
 108 \begin{verbatim}
 109       PMutex mutex;
 110
 111       ...
 112
 113       mutex.Wait();
 114
 115       ... critical section - only one thread at a time here.
 116
 117       mutex.Signal();
 118
 119       ...
 120 \end{verbatim}
 121     The first thread will pass through the #Wait()# function, a second
 122     thread will block on that function until the first calls the
 123     #Signal()# function, releasing the second thread.
 124  */
 125
 126 /*
 127  * On Windows, It is convenient for PTimedMutex to be an ancestor of PSemaphore
 128  * But that is the only platform where it is - every other platform (i.e. Unix)
 129  * uses different constructs for these objects, so there is no need for a PTimedMute
 130  * to carry around all of the PSemaphore members
 131  */
 132
 133 #ifdef _WIN32
 134 class PTimedMutex : public PSemaphore
 135 {
 136   PCLASSINFO(PTimedMutex, PSemaphore);
 137 #else
 138 class PTimedMutex : public PSync
 139 {
 140   PCLASSINFO(PTimedMutex, PSync)
 141 #endif
 142
 143   public:
 144     /* Create a new mutex.
 145        Initially the mutex will not be "set", so the first call to Wait() will
 146        never wait.
 147      */
 148     PTimedMutex();
 149     PTimedMutex(const PTimedMutex & mutex);
 150
 151 // Include platform dependent part of class
 152 #ifdef _WIN32
 153 #include "msos/ptlib/mutex.h"
 154 #else
 155 #include "unix/ptlib/mutex.h"
 156 #endif
 157 };
 158
 159 // On Windows, critical sections are recursive and so we can use them for mutexes
 160 // The only Posix mutex that is recursive is pthread_mutex, so we have to use that
 161 #ifdef _WIN32
 162 typedef PCriticalSection PMutex;
 163 #else
 164 typedef PTimedMutex PMutex;
 165 #define PCriticalSection PTimedMutex
 166 #endif
 167
 168 #endif
 169
 170 // End Of File ///////////////////////////////////////////////////////////////