dep/include/zthread/FastMutex.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 __ZTFASTMUTEX_H__
  24 #define __ZTFASTMUTEX_H__
  25
  26 #include "zthread/Lockable.h"
  27 #include "zthread/NonCopyable.h"
  28
  29 namespace ZThread {
  30
  31   class FastLock;
  32
  33   /**
  34    * @class FastMutex
  35    * @author Eric Crahen <http://www.code-foo.com>
  36    * @date <2003-07-19T18:45:39-0400>
  37    * @version 2.2.0
  38    *
  39    * A FastMutex is a small fast implementation of a non-recursive, mutually exclusive
  40    * Lockable object. This implementation is a bit faster than the other Mutex classes
  41    * as it involved the least overhead. However, this slight increase in speed is
  42    * gained by sacrificing the robustness provided by the other classes.
  43    *
  44    * A FastMutex has the useful property of not being interruptable; that is to say
  45    * that acquire() and tryAcquire() will not throw Interrupted_Exceptions.
  46    *
  47    * @see Mutex
  48    *
  49    * <b>Scheduling</b>
  50    *
  51    * Scheduling is left to the operating systems and may vary.
  52    *
  53    * <b>Error Checking</b>
  54    *
  55    * No error checking is performed, this means there is the potential for deadlock.
  56    */
  57   class ZTHREAD_API FastMutex : public Lockable, private NonCopyable {
  58
  59     FastLock* _lock;
  60
  61   public:
  62
  63     //! Create a FastMutex
  64     FastMutex();
  65
  66     //! Destroy a FastMutex
  67     virtual ~FastMutex();
  68
  69     /**
  70      * Acquire exclusive access to the mutex. The calling thread will block until the
  71      * lock can be acquired. No safety or state checks are performed.
  72      *
  73      * @pre The calling thread should <i>not</i> have previously acquired this lock.
  74      *      Deadlock will result if the same thread attempts to acquire the mutex more
  75      *      than once.
  76      *
  77      * @post The calling thread obtains the lock successfully if no exception is thrown.
  78      * @exception Interrupted_Exception never thrown
  79      */
  80     virtual void acquire();
  81
  82     /**
  83      * Release exclusive access. No safety or state checks are performed.
  84      *
  85      * @pre the caller should have previously acquired this lock
  86      */
  87     virtual void release();
  88
  89     /**
  90      * Try to acquire exclusive access to the mutex. The calling thread will block until the
  91      * lock can be acquired. No safety or state checks are performed.
  92      *
  93      * @pre The calling thread should <i>not</i> have previously acquired this lock.
  94      *      Deadlock will result if the same thread attempts to acquire the mutex more
  95      *      than once.
  96      *
  97      * @param timeout unused
  98      * @return
  99      * - <em>true</em> if the lock was acquired
 100      * - <em>false</em> if the lock was acquired
 101      *
 102      * @post The calling thread obtains the lock successfully if no exception is thrown.
 103      * @exception Interrupted_Exception never thrown
 104      */
 105     virtual bool tryAcquire(unsigned long timeout);
 106
 107   }; /* FastMutex */
 108
 109 };
 110
 111 #endif // __ZTFASTMUTEX_H__