dep/include/zthread/FastRecursiveMutex.h

   1 /*
   2  * Copyright (c) 2005, Eric Crahen
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a copy
   5  * of this software and associated documentation files (the "Software"), to deal
   6  * in the Software without restriction, including without limitation the rights
   7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   8  * copies of the Software, and to permit persons to whom the Software is furnished
   9  * to do so, subject to the following conditions:
  10  *
  11  * The above copyright notice and this permission notice shall be included in all
  12  * copies or substantial portions of the Software.
  13  *
  14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  18  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  19  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  20  *
  21  */
  22
  23 #ifndef __ZTFASTRECURSIVEMUTEX_H__
  24 #define __ZTFASTRECURSIVEMUTEX_H__
  25
  26 #include "zthread/Lockable.h"
  27 #include "zthread/NonCopyable.h"
  28
  29 namespace ZThread {
  30
  31   class FastRecursiveLock;
  32
  33   /**
  34    * @class FastRecursiveMutex
  35    *
  36    * @author Eric Crahen <http://www.code-foo.com>
  37    * @date <2003-07-19T19:00:25-0400>
  38    * @version 2.2.0
  39    *
  40    * A FastRecursiveMutex is a small fast implementation of a recursive, mutally exclusive
  41    * Lockable object. This implementation is a bit faster than the other Mutex classes
  42    * as it involved the least overhead. However, this slight increase in speed is
  43    * gained by sacrificing the robustness provided by the other classes.
  44    *
  45    * A FastRecursiveMutex has the useful property of not being interruptable; that is to say
  46    * that acquire() and tryAcquire() will not throw Interrupted_Exceptions.
  47    *
  48    * @see RecursiveMutex
  49    *
  50    * <b>Scheduling</b>
  51    *
  52    * Scheduling is left to the operating systems and may vary.
  53    *
  54    * <b>Error Checking</b>
  55    *
  56    * No error checking is performed, this means there is the potential for deadlock.
  57    */
  58   class ZTHREAD_API FastRecursiveMutex : public Lockable, private NonCopyable {
  59
  60     FastRecursiveLock* _lock;
  61
  62   public:
  63
  64     //! Create a new FastRecursiveMutex
  65     FastRecursiveMutex();
  66
  67     //! Destroy this FastRecursiveMutex
  68     virtual ~FastRecursiveMutex();
  69
  70     /**
  71      * Acquire exclusive access to the mutex. The calling thread will block until the
  72      * lock can be acquired. No safety or state checks are performed. The calling thread
  73      * may acquire the mutex nore than once.
  74      *
  75      * @post The calling thread obtains the lock successfully if no exception is thrown.
  76      * @exception Interrupted_Exception never thrown
  77      */
  78     virtual void acquire();
  79
  80     /**
  81      * Release access. No safety or state checks are performed.
  82      *
  83      * @pre the caller should have previously acquired this lock at least once.
  84      */
  85     virtual void release();
  86
  87     /**
  88      * Try to acquire exclusive access to the mutex. The calling thread will block until the
  89      * lock can be acquired. No safety or state checks are performed. The calling thread
  90      * may acquire the mutex more than once.
  91      *
  92      * @param timeout unused
  93      * @return
  94      * - <em>true</em> if the lock was acquired
  95      * - <em>false</em> if the lock was acquired
  96      *
  97      * @post The calling thread obtains the lock successfully if no exception is thrown.
  98      * @exception Interrupted_Exception never thrown
  99      */
 100     virtual bool tryAcquire(unsigned long timeout);
 101
 102   };
 103
 104 } // namespace ZThread
 105
 106 #endif // __ZTFASTRECURSIVEMUTEX_H__