include/ptlib/syncthrd.h

   1 /*
   2  * syncthrd.h
   3  *
   4  * Various thread synchronisation classes.
   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.13  2004/03/22 10:15:27  rjongbloed
  31  * Added classes similar to PWaitAndSignal to automatically unlock a PReadWriteMutex
  32  *   when goes out of scope.
  33  *
  34  * Revision 1.12  2002/12/11 03:21:28  robertj
  35  * Updated documentation for read/write mutex.
  36  *
  37  * Revision 1.11  2002/10/04 08:20:44  robertj
  38  * Changed read/write mutex so can be called by same thread without deadlock.
  39  *
  40  * Revision 1.10  2002/09/16 01:08:59  robertj
  41  * Added #define so can select if #pragma interface/implementation is used on
  42  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  43  *
  44  * Revision 1.9  2002/05/01 03:45:31  robertj
  45  * Added initialisation of PreadWriteMutex and changed slightly to agree
  46  *   with the text book definition of a semaphore for one of the mutexes.
  47  *
  48  * Revision 1.8  2002/04/30 06:21:54  robertj
  49  * Fixed PReadWriteMutex class to implement text book algorithm!
  50  *
  51  * Revision 1.7  2001/05/22 12:49:32  robertj
  52  * Did some seriously wierd rewrite of platform headers to eliminate the
  53  *   stupid GNU compiler warning about braces not matching.
  54  *
  55  * Revision 1.6  1999/03/09 02:59:51  robertj
  56  * Changed comments to doc++ compatible documentation.
  57  *
  58  * Revision 1.5  1999/02/16 08:11:17  robertj
  59  * MSVC 6.0 compatibility changes.
  60  *
  61  * Revision 1.4  1998/11/30 02:52:01  robertj
  62  * New directory structure
  63  *
  64  * Revision 1.3  1998/10/31 12:46:45  robertj
  65  * Renamed file for having general thread synchronisation objects.
  66  * Added conditional mutex and read/write mutex thread synchronisation objects.
  67  *
  68  * Revision 1.2  1998/09/23 06:21:35  robertj
  69  * Added open source copyright license.
  70  *
  71  * Revision 1.1  1998/05/30 13:26:15  robertj
  72  * Initial revision
  73  *
  74  */
  75
  76
  77 #define _PSYNCPOINTACK
  78
  79 #ifdef P_USE_PRAGMA
  80 #pragma interface
  81 #endif
  82
  83 #include <ptlib/mutex.h>
  84 #include <ptlib/syncpoint.h>
  85
  86 /** This class defines a thread synchonisation object.
  87
  88    This may be used to send signals to a thread and await an acknowldegement
  89    that the signal was processed. This can be be used to initate an action in
  90    another thread and wait for the action to be completed.
  91 \begin{verbatim}
  92     ... thread one
  93     while (condition) {
  94       sync.Wait();
  95       do_something();
  96       sync.Acknowledge();
  97     }
  98
  99     ... thread 2
 100     do_something_else();
 101     sync.Signal();    // At this point thread 1 wake up and does something.
 102     do_yet_more();    // However, this does not get done until Acknowldege()
 103                       // is called in the other thread.
 104
 105 \end{verbatim}
 106  */
 107 class PSyncPointAck : public PSyncPoint
 108 {
 109   PCLASSINFO(PSyncPointAck, PSyncPoint);
 110
 111   public:
 112     /** If there are waiting (blocked) threads then unblock the first one that
 113        was blocked. If no waiting threads and the count is less than the
 114        maximum then increment the semaphore.
 115
 116        Unlike the PSyncPoint::Signal() this function will block until the
 117        target thread that was blocked by the Wait() function has resumed
 118        execution and called the Acknowledge() function.
 119
 120        The #waitTime# parameter is used as a maximum amount of time
 121        to wait for the achnowledgement to be returned from the other thread.
 122      */
 123     virtual void Signal();
 124     void Signal(const PTimeInterval & waitTime);
 125
 126     /** This indicates that the thread that was blocked in a Wait() on this
 127        synchonrisation object has completed the operation the signal was
 128        intended to initiate. This unblocks the thread that had called the
 129        Signal() function to initiate the action.
 130      */
 131     void Acknowledge();
 132
 133   protected:
 134     PSyncPoint ack;
 135 };
 136
 137
 138 /**This class defines a thread synchonisation object.
 139
 140    This is a special type of mutual exclusion, where a thread wishes to get
 141    exlusive use of a resource but only if a certain other condition is met.
 142  */
 143 class PCondMutex : public PMutex
 144 {
 145   PCLASSINFO(PCondMutex, PMutex);
 146
 147   public:
 148     /** This function attempts to acquire the mutex, but will block not only
 149        until the mutex is free, but also that the condition returned by the
 150        Condition() function is also met.
 151      */
 152     virtual void WaitCondition();
 153
 154     /** If there are waiting (blocked) threads then unblock the first one that
 155        was blocked. If no waiting threads and the count is less than the
 156        maximum then increment the semaphore.
 157      */
 158     virtual void Signal();
 159
 160     /** This is the condition that must be met for the WaitCondition() function
 161        to acquire the mutex.
 162      */
 163     virtual BOOL Condition() = 0;
 164
 165     /** This function is called immediately before blocking on the condition in
 166        the WaitCondition() function. This could get called multiple times
 167        before the condition is met and the WaitCondition() function returns.
 168      */
 169     virtual void OnWait();
 170
 171   protected:
 172     PSyncPoint syncPoint;
 173 };
 174
 175
 176 /** This is a PCondMutex for which the conditional is the value of an integer.
 177  */
 178 class PIntCondMutex : public PCondMutex
 179 {
 180   PCLASSINFO(PIntCondMutex, PCondMutex);
 181
 182   public:
 183   /**@name Construction */
 184   //@{
 185     /// defines possible operators on current value and target value
 186     enum Operation {
 187       /// Less than
 188       LT,
 189       /// Less than or equal to
 190       LE,
 191       /// Equal to
 192       EQ,
 193       /// Greater than or equal to
 194       GE,
 195       /// Greater than
 196       GT
 197     };
 198
 199     /**
 200       Create a cond mutex using an integer
 201     */
 202     PIntCondMutex(
 203       int value = 0,            /// initial value if the integer
 204       int target = 0,           /// target vaue which causes the mutex to unlock
 205       Operation operation = LE  /// comparison operator
 206     );
 207   //@}
 208
 209   /**@name Overrides from class PObject */
 210   //@{
 211     /** Print the object on the stream. This will be of the form
 212        #"(value < target)"#.
 213      */
 214     void PrintOn(ostream & strm) const;
 215   //@}
 216
 217   /**@name Condition access functions */
 218   //@{
 219     /** This is the condition that must be met for the WaitCondition() function
 220        to acquire the mutex.
 221
 222        @return TRUE if condition is met.
 223      */
 224     virtual BOOL Condition();
 225
 226     /**Get the current value of the condition variable.
 227       @return Current condition variable value.
 228      */
 229     operator int() const { return value; }
 230
 231     /**Assign new condition value.
 232        Use the Wait() function to acquire the mutex, modify the value, then
 233        release the mutex, possibly releasing the thread in the WaitCondition()
 234        function if the condition was met by the operation.
 235
 236        @return The object reference for consecutive operations in the same statement.
 237      */
 238     PIntCondMutex & operator=(int newval);
 239
 240     /**Increment condition value.
 241        Use the Wait() function to acquire the mutex, modify the value, then
 242        release the mutex, possibly releasing the thread in the WaitCondition()
 243        function if the condition was met by the operation.
 244
 245        @return The object reference for consecutive operations in the same statement.
 246      */
 247     PIntCondMutex & operator++();
 248
 249     /**Add to condition value.
 250        Use the Wait() function to acquire the mutex, modify the value, then
 251        release the mutex, possibly releasing the thread in the WaitCondition()
 252        function if the condition was met by the operation.
 253
 254        @return The object reference for consecutive operations in the same statement.
 255      */
 256     PIntCondMutex & operator+=(int inc);
 257
 258     /**Decrement condition value.
 259        Use the Wait() function to acquire the mutex, modify the value, then
 260        release the mutex, possibly releasing the thread in the WaitCondition()
 261        function if the condition was met by the operation.
 262
 263        @return The object reference for consecutive operations in the same statement.
 264      */
 265     PIntCondMutex & operator--();
 266
 267     /**Subtract from condition value.
 268        Use the Wait() function to acquire the mutex, modify the value, then
 269        release the mutex, possibly releasing the thread in the WaitCondition()
 270        function if the condition was met by the operation.
 271
 272        @return The object reference for consecutive operations in the same statement.
 273      */
 274     PIntCondMutex & operator-=(int dec);
 275   //@}
 276
 277
 278   protected:
 279     int value, target;
 280     Operation operation;
 281 };
 282
 283
 284 /** This class defines a thread synchonisation object.
 285
 286    This is a special type of mutual exclusion, where the excluded area may
 287    have multiple read threads but only one write thread and the read threads
 288    are blocked on write as well.
 289  */
 290
 291 class PReadWriteMutex : public PObject
 292 {
 293   PCLASSINFO(PReadWriteMutex, PObject);
 294   public:
 295   /**@name Construction */
 296   //@{
 297     PReadWriteMutex();
 298   //@}
 299
 300   /**@name Operations */
 301   //@{
 302     /** This function attempts to acquire the mutex for reading.
 303         This call may be nested and must have an equal number of EndRead()
 304         calls for the mutex to be released.
 305      */
 306     void StartRead();
 307
 308     /** This function attempts to release the mutex for reading.
 309      */
 310     void EndRead();
 311
 312     /** This function attempts to acquire the mutex for writing.
 313         This call may be nested and must have an equal number of EndWrite()
 314         calls for the mutex to be released.
 315
 316         Note, if the same thread had a read lock previous to this call then
 317         the read lock is automatically released and reacquired when EndWrite()
 318         is called, unless an EndRead() is called. The EndRead() and EndWrite()
 319         calls do not have to be strictly nested.
 320
 321         It should also be noted that a consequence of this is that another
 322         thread may acquire the write lock before the thread that previously
 323         had the read lock. Thus it is impossibly to go straight from a read
 324         lock to write lock without the possiblility of the object being
 325         changed and application logic should take this into account.
 326      */
 327     void StartWrite();
 328
 329     /** This function attempts to release the mutex for writing.
 330         Note, if the same thread had a read lock when the StartWrite() was
 331         called which has not yet been released by an EndRead() call then this
 332         will reacquire the read lock.
 333
 334         It should also be noted that a consequence of this is that another
 335         thread may acquire the write lock before the thread that regains the
 336         read lock. Thus it is impossibly to go straight from a write lock to
 337         read lock without the possiblility of the object being changed and
 338         application logic should take this into account.
 339      */
 340     void EndWrite();
 341   //@}
 342
 343   protected:
 344     PSemaphore readerSemaphore;
 345     PMutex     readerMutex;
 346     unsigned   readerCount;
 347     PMutex     starvationPreventer;
 348
 349     PSemaphore writerSemaphore;
 350     PMutex     writerMutex;
 351     unsigned   writerCount;
 352
 353     class Nest : public PObject
 354     {
 355       PCLASSINFO(Nest, PObject);
 356       Nest() { readerCount = writerCount = 0; }
 357       unsigned readerCount;
 358       unsigned writerCount;
 359     };
 360     PDictionary<POrdinalKey, Nest> nestedThreads;
 361     PMutex                         nestingMutex;
 362
 363     Nest * GetNest() const;
 364     Nest & StartNest();
 365     void EndNest();
 366     void InternalStartRead();
 367     void InternalEndRead();
 368 };
 369
 370
 371 /**This class starts a read operation for the PReadWriteMutex on construction
 372    and automatically ends the read operation on destruction.
 373
 374   This is very usefull for constructs such as:
 375 \begin{verbatim}
 376     void func()
 377     {
 378       PReadWaitAndSignal mutexWait(myMutex);
 379       if (condition)
 380         return;
 381       do_something();
 382       if (other_condition)
 383         return;
 384       do_something_else();
 385     }
 386 \end{verbatim}
 387  */
 388 class PReadWaitAndSignal {
 389   public:
 390     /**Create the PReadWaitAndSignal wait instance.
 391        This will wait on the specified PReadWriteMutex using the #StartRead()#
 392        function before returning.
 393       */
 394     PReadWaitAndSignal(
 395       const PReadWriteMutex & rw,   /// PReadWriteMutex descendent to wait/signal.
 396       BOOL start = TRUE    /// Start read operation on PReadWriteMutex before returning.
 397     );
 398     /** End read operation on the PReadWriteMutex.
 399         This will execute the EndRead() function on the PReadWriteMutex that
 400         was used in the construction of this instance.
 401      */
 402     ~PReadWaitAndSignal();
 403
 404   protected:
 405     PReadWriteMutex & mutex;
 406 };
 407
 408
 409 /**This class starts a write operation for the PReadWriteMutex on construction
 410    and automatically ends the write operation on destruction.
 411
 412   This is very usefull for constructs such as:
 413 \begin{verbatim}
 414     void func()
 415     {
 416       PWriteWaitAndSignal mutexWait(myMutex);
 417       if (condition)
 418         return;
 419       do_something();
 420       if (other_condition)
 421         return;
 422       do_something_else();
 423     }
 424 \end{verbatim}
 425  */
 426 class PWriteWaitAndSignal {
 427   public:
 428     /**Create the PWriteWaitAndSignal wait instance.
 429        This will wait on the specified PReadWriteMutex using the #StartWrite()#
 430        function before returning.
 431       */
 432     PWriteWaitAndSignal(
 433       const PReadWriteMutex & rw,   /// PReadWriteMutex descendent to wait/signal.
 434       BOOL start = TRUE    /// Start write operation on PReadWriteMutex before returning.
 435     );
 436     /** End write operation on the PReadWriteMutex.
 437         This will execute the EndWrite() function on the PReadWriteMutex that
 438         was used in the construction of this instance.
 439      */
 440     ~PWriteWaitAndSignal();
 441
 442   protected:
 443     PReadWriteMutex & mutex;
 444 };
 445
 446
 447 // End Of File ///////////////////////////////////////////////////////////////