dep/include/zthread/Mutex.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 __ZTMUTEX_H__
  24 #define __ZTMUTEX_H__
  25
  26 #include "zthread/Lockable.h"
  27 #include "zthread/NonCopyable.h"
  28
  29 namespace ZThread {
  30
  31   class FifoMutexImpl;
  32
  33   /**
  34    * @class Mutex
  35    * @author Eric Crahen <http://www.code-foo.com>
  36    * @date <2003-07-16T19:35:28-0400>
  37    * @version 2.2.1
  38    *
  39    * A Mutex is used to provide serialized (one thread at a time) access to some portion
  40    * of code. This is accomplished by attempting to acquire the Mutex before entering that
  41    * piece of code, and by releasing the Mutex when leaving that region. It is a non-reentrant,
  42    * MUTual EXclusion Lockable object.
  43    *
  44    * @see Guard
  45    *
  46    * <b>Scheduling</b>
  47    *
  48    * Threads competing to acquire() a Mutex are granted access in FIFO order.
  49    *
  50    * <b>Error Checking</b>
  51    *
  52    * A Mutex will throw a Deadlock_Exception if an attempt to acquire a Mutex more
  53    * than once is made from the context of the same thread.
  54    *
  55    * A Mutex will throw an InvalidOp_Exception if an attempt to release a Mutex is
  56    * made from the context of a thread that does not currently own that Mutex.
  57    */
  58   class ZTHREAD_API Mutex : public Lockable, private NonCopyable {
  59
  60     FifoMutexImpl* _impl;
  61
  62   public:
  63
  64     //! Create a new Mutex.
  65     Mutex();
  66
  67     //! Destroy this Mutex.
  68     virtual ~Mutex();
  69
  70     /**
  71      * Acquire a Mutex, possibly blocking until either the current owner of the
  72      * Mutex releases it or until an exception is thrown.
  73      *
  74      * Only one thread may acquire() the Mutex at any given time.
  75      *
  76      * @exception Interrupted_Exception thrown when the calling thread is interrupted.
  77      *            A thread may be interrupted at any time, prematurely ending any wait.
  78      * @exception Deadlock_Exception thrown when the same thread attempts to acquire
  79      *            a Mutex more than once, without having first release()ed it.
  80      *
  81      * @pre the calling thread must not have already acquired Mutex
  82      *
  83      * @post the calling thread successfully acquired Mutex only if no exception
  84      *       was thrown.
  85      *
  86      * @see Lockable::acquire()
  87      */
  88     virtual void acquire();
  89
  90     /**
  91      * Acquire a Mutex, possibly blocking until the current owner of the
  92      * Mutex releases it, until an exception is thrown or until the given amount
  93      * of time expires.
  94      *
  95      * Only one thread may acquire the Mutex at any given time.
  96      *
  97      * @param timeout maximum amount of time (milliseconds) this method could block
  98      * @return
  99      * - <em>true</em> if the lock was acquired
 100      * - <em>false</em> if the lock was acquired
 101      *
 102      * @exception Interrupted_Exception thrown when the calling thread is interrupted.
 103      *            A thread may be interrupted at any time, prematurely ending any wait.
 104      * @exception Deadlock_Exception thrown when the same thread attempts to acquire
 105      *            a Mutex more than once, without having first released it.
 106      *
 107      * @pre the calling thread must not have already acquired Mutex
 108      *
 109      * @post the calling thread successfully acquired Mutex only if no exception
 110      *       was thrown.
 111      *
 112      * @see Lockable::tryAcquire(unsigned long timeout)
 113      */
 114     virtual bool tryAcquire(unsigned long timeout);
 115
 116     /**
 117      * Release a Mutex allowing another thread to acquire it.
 118      *
 119      * @exception InvalidOp_Exception - thrown if there is an attempt to release is
 120      *            a Mutex that was not owner by the calling thread.
 121      *
 122      * @pre  the calling thread must have first acquired the Mutex.
 123      * @post the calling thread successfully released Mutex only if no exception
 124      *       was thrown.
 125      *
 126      * @see Lockable::release()
 127      */
 128     virtual void release();
 129
 130   };
 131
 132
 133 } // namespace ZThread
 134
 135 #endif // __ZTMUTEX_H__