xpcom/glue/Mutex.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * vim: sw=4 ts=4 et :
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is mozilla.org code.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications Corporation.
  20  * Portions created by the Initial Developer are Copyright (C) 1998
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #ifndef mozilla_Mutex_h
  40 #define mozilla_Mutex_h
  41
  42 #include "prlock.h"
  43
  44 #include "mozilla/AutoRestore.h"
  45 #include "mozilla/BlockingResourceBase.h"
  46
  47 //
  48 // Provides:
  49 //
  50 //  - Mutex, a non-recursive mutex
  51 //  - MutexAutoLock, an RAII class for ensuring that Mutexes are properly
  52 //    locked and unlocked
  53 //  - MutexAutoUnlock, complementary sibling to MutexAutoLock
  54 //
  55 // Using MutexAutoLock/MutexAutoUnlock is MUCH preferred to making bare
  56 // calls to Mutex.Lock and Unlock.
  57 //
  58 namespace mozilla {
  59
  60
  61 /**
  62  * Mutex
  63  * When possible, use MutexAutoLock/MutexAutoUnlock to lock/unlock this
  64  * mutex within a scope, instead of calling Lock/Unlock directly.
  65  **/
  66
  67 class NS_COM_GLUE Mutex : BlockingResourceBase
  68 {
  69 public:
  70     /**
  71      * Mutex
  72      * @param name A name which can reference this lock
  73      * @returns If failure, nsnull
  74      *          If success, a valid Mutex* which must be destroyed
  75      *          by Mutex::DestroyMutex()
  76      **/
  77     Mutex(const char* name) :
  78         BlockingResourceBase(name, eMutex)
  79     {
  80         mLock = PR_NewLock();
  81         if (!mLock)
  82             NS_RUNTIMEABORT("Can't allocate mozilla::Mutex");
  83     }
  84
  85     /**
  86      * ~Mutex
  87      **/
  88     ~Mutex()
  89     {
  90         NS_ASSERTION(mLock,
  91                      "improperly constructed Lock or double free");
  92         // NSPR does consistency checks for us
  93         PR_DestroyLock(mLock);
  94         mLock = 0;
  95     }
  96
  97 #ifndef DEBUG
  98     /**
  99      * Lock
 100      * @see prlock.h
 101      **/
 102     void Lock()
 103     {
 104         PR_Lock(mLock);
 105     }
 106
 107     /**
 108      * Unlock
 109      * @see prlock.h
 110      **/
 111     void Unlock()
 112     {
 113         PR_Unlock(mLock);
 114     }
 115
 116     /**
 117      * AssertCurrentThreadOwns
 118      * @see prlock.h
 119      **/
 120     void AssertCurrentThreadOwns () const
 121     {
 122     }
 123
 124     /**
 125      * AssertNotCurrentThreadOwns
 126      * @see prlock.h
 127      **/
 128     void AssertNotCurrentThreadOwns () const
 129     {
 130     }
 131
 132 #else
 133     void Lock();
 134     void Unlock();
 135
 136     void AssertCurrentThreadOwns () const
 137     {
 138         PR_ASSERT_CURRENT_THREAD_OWNS_LOCK(mLock);
 139     }
 140
 141     void AssertNotCurrentThreadOwns () const
 142     {
 143         // FIXME bug 476536
 144     }
 145
 146 #endif  // ifndef DEBUG
 147
 148 private:
 149     Mutex();
 150     Mutex(const Mutex&);
 151     Mutex& operator=(const Mutex&);
 152
 153     PRLock* mLock;
 154
 155     friend class CondVar;
 156 };
 157
 158
 159 /**
 160  * MutexAutoLock
 161  * Acquires the Mutex when it enters scope, and releases it when it leaves
 162  * scope.
 163  *
 164  * MUCH PREFERRED to bare calls to Mutex.Lock and Unlock.
 165  */
 166 class NS_COM_GLUE NS_STACK_CLASS MutexAutoLock
 167 {
 168 public:
 169     /**
 170      * Constructor
 171      * The constructor aquires the given lock.  The destructor
 172      * releases the lock.
 173      *
 174      * @param aLock A valid mozilla::Mutex* returned by
 175      *              mozilla::Mutex::NewMutex.
 176      **/
 177     MutexAutoLock(mozilla::Mutex& aLock MOZILLA_GUARD_OBJECT_NOTIFIER_PARAM) :
 178         mLock(&aLock)
 179     {
 180         MOZILLA_GUARD_OBJECT_NOTIFIER_INIT;
 181         NS_ASSERTION(mLock, "null mutex");
 182         mLock->Lock();
 183     }
 184
 185     ~MutexAutoLock(void) {
 186         mLock->Unlock();
 187     }
 188
 189 private:
 190     MutexAutoLock();
 191     MutexAutoLock(MutexAutoLock&);
 192     MutexAutoLock& operator=(MutexAutoLock&);
 193     static void* operator new(size_t) CPP_THROW_NEW;
 194     static void operator delete(void*);
 195
 196     mozilla::Mutex* mLock;
 197     MOZILLA_DECL_USE_GUARD_OBJECT_NOTIFIER
 198 };
 199
 200
 201 /**
 202  * MutexAutoUnlock
 203  * Releases the Mutex when it enters scope, and re-acquires it when it leaves
 204  * scope.
 205  *
 206  * MUCH PREFERRED to bare calls to Mutex.Unlock and Lock.
 207  */
 208 class NS_COM_GLUE NS_STACK_CLASS MutexAutoUnlock
 209 {
 210 public:
 211     MutexAutoUnlock(mozilla::Mutex& aLock MOZILLA_GUARD_OBJECT_NOTIFIER_PARAM) :
 212         mLock(&aLock)
 213     {
 214         MOZILLA_GUARD_OBJECT_NOTIFIER_INIT;
 215         NS_ASSERTION(mLock, "null lock");
 216         mLock->Unlock();
 217     }
 218
 219     ~MutexAutoUnlock()
 220     {
 221         mLock->Lock();
 222     }
 223
 224 private:
 225     MutexAutoUnlock();
 226     MutexAutoUnlock(MutexAutoUnlock&);
 227     MutexAutoUnlock& operator =(MutexAutoUnlock&);
 228     static void* operator new(size_t) CPP_THROW_NEW;
 229     static void operator delete(void*);
 230
 231     mozilla::Mutex* mLock;
 232     MOZILLA_DECL_USE_GUARD_OBJECT_NOTIFIER
 233 };
 234
 235
 236 } // namespace mozilla
 237
 238
 239 #endif // ifndef mozilla_Mutex_h