juce/source/src/threads/juce_ScopedLock.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_SCOPEDLOCK_JUCEHEADER__
  27 #define __JUCE_SCOPEDLOCK_JUCEHEADER__
  28
  29
  30 //==============================================================================
  31 /**
  32     Automatically locks and unlocks a mutex object.
  33
  34     Use one of these as a local variable to provide RAII-based locking of a mutex.
  35
  36     The templated class could be a CriticalSection, SpinLock, or anything else that
  37     provides enter() and exit() methods.
  38
  39     e.g. @code
  40     CriticalSection myCriticalSection;
  41
  42     for (;;)
  43     {
  44         const GenericScopedLock<CriticalSection> myScopedLock (myCriticalSection);
  45         // myCriticalSection is now locked
  46
  47         ...do some stuff...
  48
  49         // myCriticalSection gets unlocked here.
  50     }
  51     @endcode
  52
  53     @see GenericScopedUnlock, CriticalSection, SpinLock, ScopedLock, ScopedUnlock
  54 */
  55 template <class LockType>
  56 class GenericScopedLock
  57 {
  58 public:
  59     //==============================================================================
  60     /** Creates a GenericScopedLock.
  61
  62         As soon as it is created, this will acquire the lock, and when the GenericScopedLock
  63         object is deleted, the lock will be released.
  64
  65         Make sure this object is created and deleted by the same thread,
  66         otherwise there are no guarantees what will happen! Best just to use it
  67         as a local stack object, rather than creating one with the new() operator.
  68     */
  69     inline explicit GenericScopedLock (const LockType& lock) noexcept : lock_ (lock)     { lock.enter(); }
  70
  71     /** Destructor.
  72         The lock will be released when the destructor is called.
  73         Make sure this object is created and deleted by the same thread, otherwise there are
  74         no guarantees what will happen!
  75     */
  76     inline ~GenericScopedLock() noexcept                                                 { lock_.exit(); }
  77
  78 private:
  79     //==============================================================================
  80     const LockType& lock_;
  81
  82     JUCE_DECLARE_NON_COPYABLE (GenericScopedLock);
  83 };
  84
  85
  86 //==============================================================================
  87 /**
  88     Automatically unlocks and re-locks a mutex object.
  89
  90     This is the reverse of a GenericScopedLock object - instead of locking the mutex
  91     for the lifetime of this object, it unlocks it.
  92
  93     Make sure you don't try to unlock mutexes that aren't actually locked!
  94
  95     e.g. @code
  96
  97     CriticalSection myCriticalSection;
  98
  99     for (;;)
 100     {
 101         const GenericScopedLock<CriticalSection> myScopedLock (myCriticalSection);
 102         // myCriticalSection is now locked
 103
 104         ... do some stuff with it locked ..
 105
 106         while (xyz)
 107         {
 108             ... do some stuff with it locked ..
 109
 110             const GenericScopedUnlock<CriticalSection> unlocker (myCriticalSection);
 111
 112             // myCriticalSection is now unlocked for the remainder of this block,
 113             // and re-locked at the end.
 114
 115             ...do some stuff with it unlocked ...
 116         }
 117
 118         // myCriticalSection gets unlocked here.
 119     }
 120     @endcode
 121
 122     @see GenericScopedLock, CriticalSection, ScopedLock, ScopedUnlock
 123 */
 124 template <class LockType>
 125 class GenericScopedUnlock
 126 {
 127 public:
 128     //==============================================================================
 129     /** Creates a GenericScopedUnlock.
 130
 131         As soon as it is created, this will unlock the CriticalSection, and
 132         when the ScopedLock object is deleted, the CriticalSection will
 133         be re-locked.
 134
 135         Make sure this object is created and deleted by the same thread,
 136         otherwise there are no guarantees what will happen! Best just to use it
 137         as a local stack object, rather than creating one with the new() operator.
 138     */
 139     inline explicit GenericScopedUnlock (const LockType& lock) noexcept : lock_ (lock)   { lock.exit(); }
 140
 141     /** Destructor.
 142
 143         The CriticalSection will be unlocked when the destructor is called.
 144
 145         Make sure this object is created and deleted by the same thread,
 146         otherwise there are no guarantees what will happen!
 147     */
 148     inline ~GenericScopedUnlock() noexcept                                               { lock_.enter(); }
 149
 150
 151 private:
 152     //==============================================================================
 153     const LockType& lock_;
 154
 155     JUCE_DECLARE_NON_COPYABLE (GenericScopedUnlock);
 156 };
 157
 158
 159 //==============================================================================
 160 /**
 161     Automatically locks and unlocks a mutex object.
 162
 163     Use one of these as a local variable to provide RAII-based locking of a mutex.
 164
 165     The templated class could be a CriticalSection, SpinLock, or anything else that
 166     provides enter() and exit() methods.
 167
 168     e.g. @code
 169
 170     CriticalSection myCriticalSection;
 171
 172     for (;;)
 173     {
 174         const GenericScopedTryLock<CriticalSection> myScopedTryLock (myCriticalSection);
 175
 176         // Unlike using a ScopedLock, this may fail to actually get the lock, so you
 177         // should test this with the isLocked() method before doing your thread-unsafe
 178         // action..
 179         if (myScopedTryLock.isLocked())
 180         {
 181            ...do some stuff...
 182         }
 183         else
 184         {
 185             ..our attempt at locking failed because another thread had already locked it..
 186         }
 187
 188         // myCriticalSection gets unlocked here (if it was locked)
 189     }
 190     @endcode
 191
 192     @see CriticalSection::tryEnter, GenericScopedLock, GenericScopedUnlock
 193 */
 194 template <class LockType>
 195 class GenericScopedTryLock
 196 {
 197 public:
 198     //==============================================================================
 199     /** Creates a GenericScopedTryLock.
 200
 201         As soon as it is created, this will attempt to acquire the lock, and when the
 202         GenericScopedTryLock is deleted, the lock will be released (if the lock was
 203         successfully acquired).
 204
 205         Make sure this object is created and deleted by the same thread,
 206         otherwise there are no guarantees what will happen! Best just to use it
 207         as a local stack object, rather than creating one with the new() operator.
 208     */
 209     inline explicit GenericScopedTryLock (const LockType& lock) noexcept
 210         : lock_ (lock), lockWasSuccessful (lock.tryEnter()) {}
 211
 212     /** Destructor.
 213
 214         The mutex will be unlocked (if it had been successfully locked) when the
 215         destructor is called.
 216
 217         Make sure this object is created and deleted by the same thread,
 218         otherwise there are no guarantees what will happen!
 219     */
 220     inline ~GenericScopedTryLock() noexcept         { if (lockWasSuccessful) lock_.exit(); }
 221
 222     /** Returns true if the mutex was successfully locked. */
 223     bool isLocked() const noexcept                  { return lockWasSuccessful; }
 224
 225 private:
 226     //==============================================================================
 227     const LockType& lock_;
 228     const bool lockWasSuccessful;
 229
 230     JUCE_DECLARE_NON_COPYABLE (GenericScopedTryLock);
 231 };
 232
 233
 234 #endif   // __JUCE_SCOPEDLOCK_JUCEHEADER__