juce/source/src/threads/juce_CriticalSection.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_CRITICALSECTION_JUCEHEADER__
  27 #define __JUCE_CRITICALSECTION_JUCEHEADER__
  28
  29 #include "juce_ScopedLock.h"
  30
  31
  32 //==============================================================================
  33 /**
  34     A mutex class.
  35
  36     A CriticalSection acts as a re-entrant mutex lock. The best way to lock and unlock
  37     one of these is by using RAII in the form of a local ScopedLock object - have a look
  38     through the codebase for many examples of how to do this.
  39
  40     @see ScopedLock, ScopedTryLock, ScopedUnlock, SpinLock, ReadWriteLock, Thread, InterProcessLock
  41 */
  42 class JUCE_API  CriticalSection
  43 {
  44 public:
  45     //==============================================================================
  46     /** Creates a CriticalSection object. */
  47     CriticalSection() noexcept;
  48
  49     /** Destructor.
  50         If the critical section is deleted whilst locked, any subsequent behaviour
  51         is unpredictable.
  52     */
  53     ~CriticalSection() noexcept;
  54
  55     //==============================================================================
  56     /** Acquires the lock.
  57
  58         If the lock is already held by the caller thread, the method returns immediately.
  59         If the lock is currently held by another thread, this will wait until it becomes free.
  60
  61         It's strongly recommended that you never call this method directly - instead use the
  62         ScopedLock class to manage the locking using an RAII pattern instead.
  63
  64         @see exit, tryEnter, ScopedLock
  65     */
  66     void enter() const noexcept;
  67
  68     /** Attempts to lock this critical section without blocking.
  69
  70         This method behaves identically to CriticalSection::enter, except that the caller thread
  71         does not wait if the lock is currently held by another thread but returns false immediately.
  72
  73         @returns false if the lock is currently held by another thread, true otherwise.
  74         @see enter
  75     */
  76     bool tryEnter() const noexcept;
  77
  78     /** Releases the lock.
  79
  80         If the caller thread hasn't got the lock, this can have unpredictable results.
  81
  82         If the enter() method has been called multiple times by the thread, each
  83         call must be matched by a call to exit() before other threads will be allowed
  84         to take over the lock.
  85
  86         @see enter, ScopedLock
  87     */
  88     void exit() const noexcept;
  89
  90
  91     //==============================================================================
  92     /** Provides the type of scoped lock to use with a CriticalSection. */
  93     typedef GenericScopedLock <CriticalSection>       ScopedLockType;
  94
  95     /** Provides the type of scoped unlocker to use with a CriticalSection. */
  96     typedef GenericScopedUnlock <CriticalSection>     ScopedUnlockType;
  97
  98     /** Provides the type of scoped try-locker to use with a CriticalSection. */
  99     typedef GenericScopedTryLock <CriticalSection>    ScopedTryLockType;
 100
 101
 102 private:
 103     //==============================================================================
 104    #if JUCE_WINDOWS
 105     // To avoid including windows.h in the public JUCE headers, we'll just allocate a
 106     // block of memory here that's big enough to be used internally as a windows critical
 107     // section structure.
 108     #if JUCE_64BIT
 109      uint8 internal [44];
 110     #else
 111      uint8 internal [24];
 112     #endif
 113    #else
 114     mutable pthread_mutex_t internal;
 115    #endif
 116
 117     JUCE_DECLARE_NON_COPYABLE (CriticalSection);
 118 };
 119
 120
 121 //==============================================================================
 122 /**
 123     A class that can be used in place of a real CriticalSection object, but which
 124     doesn't perform any locking.
 125
 126     This is currently used by some templated classes, and most compilers should
 127     manage to optimise it out of existence.
 128
 129     @see CriticalSection, Array, OwnedArray, ReferenceCountedArray
 130 */
 131 class JUCE_API  DummyCriticalSection
 132 {
 133 public:
 134     inline DummyCriticalSection() noexcept      {}
 135     inline ~DummyCriticalSection() noexcept     {}
 136
 137     inline void enter() const noexcept          {}
 138     inline bool tryEnter() const noexcept       { return true; }
 139     inline void exit() const noexcept           {}
 140
 141     //==============================================================================
 142     /** A dummy scoped-lock type to use with a dummy critical section. */
 143     struct ScopedLockType
 144     {
 145         ScopedLockType (const DummyCriticalSection&) noexcept {}
 146     };
 147
 148     /** A dummy scoped-unlocker type to use with a dummy critical section. */
 149     typedef ScopedLockType ScopedUnlockType;
 150
 151 private:
 152     JUCE_DECLARE_NON_COPYABLE (DummyCriticalSection);
 153 };
 154
 155 //==============================================================================
 156 /**
 157     Automatically locks and unlocks a CriticalSection object.
 158
 159     Use one of these as a local variable to provide RAII-based locking of a CriticalSection.
 160
 161     e.g. @code
 162
 163     CriticalSection myCriticalSection;
 164
 165     for (;;)
 166     {
 167         const ScopedLock myScopedLock (myCriticalSection);
 168         // myCriticalSection is now locked
 169
 170         ...do some stuff...
 171
 172         // myCriticalSection gets unlocked here.
 173     }
 174     @endcode
 175
 176     @see CriticalSection, ScopedUnlock
 177 */
 178 typedef CriticalSection::ScopedLockType  ScopedLock;
 179
 180 //==============================================================================
 181 /**
 182     Automatically unlocks and re-locks a CriticalSection object.
 183
 184     This is the reverse of a ScopedLock object - instead of locking the critical
 185     section for the lifetime of this object, it unlocks it.
 186
 187     Make sure you don't try to unlock critical sections that aren't actually locked!
 188
 189     e.g. @code
 190
 191     CriticalSection myCriticalSection;
 192
 193     for (;;)
 194     {
 195         const ScopedLock myScopedLock (myCriticalSection);
 196         // myCriticalSection is now locked
 197
 198         ... do some stuff with it locked ..
 199
 200         while (xyz)
 201         {
 202             ... do some stuff with it locked ..
 203
 204             const ScopedUnlock unlocker (myCriticalSection);
 205
 206             // myCriticalSection is now unlocked for the remainder of this block,
 207             // and re-locked at the end.
 208
 209             ...do some stuff with it unlocked ...
 210         }
 211
 212         // myCriticalSection gets unlocked here.
 213     }
 214     @endcode
 215
 216     @see CriticalSection, ScopedLock
 217 */
 218 typedef CriticalSection::ScopedUnlockType  ScopedUnlock;
 219
 220 //==============================================================================
 221 /**
 222     Automatically tries to lock and unlock a CriticalSection object.
 223
 224     Use one of these as a local variable to control access to a CriticalSection.
 225
 226     e.g. @code
 227     CriticalSection myCriticalSection;
 228
 229     for (;;)
 230     {
 231         const ScopedTryLock myScopedTryLock (myCriticalSection);
 232
 233         // Unlike using a ScopedLock, this may fail to actually get the lock, so you
 234         // should test this with the isLocked() method before doing your thread-unsafe
 235         // action..
 236         if (myScopedTryLock.isLocked())
 237         {
 238            ...do some stuff...
 239         }
 240         else
 241         {
 242             ..our attempt at locking failed because another thread had already locked it..
 243         }
 244
 245         // myCriticalSection gets unlocked here (if it was locked)
 246     }
 247     @endcode
 248
 249     @see CriticalSection::tryEnter, ScopedLock, ScopedUnlock, ScopedReadLock
 250 */
 251 typedef CriticalSection::ScopedTryLockType  ScopedTryLock;
 252
 253
 254 #endif   // __JUCE_CRITICALSECTION_JUCEHEADER__