dep/include/zthread/CountingSemaphore.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 __ZTCOUNTINGSEMAPHORE_H__
  24 #define __ZTCOUNTINGSEMAPHORE_H__
  25
  26 #include "zthread/Lockable.h"
  27 #include "zthread/NonCopyable.h"
  28
  29 namespace ZThread {
  30
  31   class FifoSemaphoreImpl;
  32
  33   /**
  34    * @class CountingSemaphore
  35    * @author Eric Crahen <http://www.code-foo.com>
  36    * @date <2003-07-16T15:26:18-0400>
  37    * @version 2.2.1
  38    *
  39    * A CountingSemaphore is an owner-less Lockable object.
  40    *
  41    * It differs from a normal Semaphore in that there is no upper bound on the count
  42    * and it will not throw an exception because a maximum value has been exceeded.
  43    *
  44    * @see Semaphore
  45    *
  46    * Threads blocked on a CountingSemaphore are resumed in FIFO order.
  47    */
  48   class ZTHREAD_API CountingSemaphore : public Lockable, private NonCopyable {
  49
  50     FifoSemaphoreImpl* _impl;
  51
  52   public:
  53
  54     /**
  55      * Create a new CountingSemaphore.
  56      *
  57      * @param count - initial count
  58      */
  59     CountingSemaphore(int initialCount = 0);
  60
  61     //! Destroy the CountingSemaphore
  62     virtual ~CountingSemaphore();
  63
  64     /**
  65      * <i>Provided to reflect the traditional Semaphore semantics</i>
  66      *
  67      * @see acquire()
  68      */
  69     void wait();
  70
  71
  72     /**
  73      * <i>Provided to reflect the traditional Semaphore semantics</i>
  74      *
  75      * @see tryAcquire(unsigned long timeout)
  76      */
  77     bool tryWait(unsigned long timeout);
  78
  79     /**
  80      * <i>Provided to reflect the traditional Semaphore semantics</i>
  81      *
  82      * @see release()
  83      */
  84     void post();
  85
  86
  87     /**
  88      * Get the current count of the semaphore.
  89      *
  90      * This value may change immediately after this function returns to the calling thread.
  91      *
  92      * @return <em>int</em> count
  93      */
  94     virtual int count();
  95
  96     /**
  97      * Decrement the count, blocking that calling thread if the count becomes 0 or
  98      * less than 0. The calling thread will remain blocked until the count is
  99      * raised above 0, an exception is thrown or the given amount of time expires.
 100      *
 101      * @param timeout maximum amount of time (milliseconds) this method could block
 102      *
 103      * @return
 104      *   - <em>true</em> if the Semaphore was acquired before <i>timeout</i> milliseconds elapse.
 105      *   - <em>false</em> otherwise.
 106      *
 107      * @exception Interrupted_Exception thrown when the calling thread is interrupted.
 108      *            A thread may be interrupted at any time, prematurely ending any wait.
 109      *
 110      * @see Lockable::tryAcquire(unsigned long timeout)
 111      */
 112     virtual bool tryAcquire(unsigned long timeout);
 113
 114     /**
 115      * Decrement the count, blocking that calling thread if the count becomes 0 or
 116      * less than 0. The calling thread will remain blocked until the count is
 117      * raised above 0 or if an exception is thrown.
 118      *
 119      * @exception Interrupted_Exception thrown when the calling thread is interrupted.
 120      *            A thread may be interrupted at any time, prematurely ending any wait.
 121      *
 122      * @see Lockable::acquire()
 123      */
 124     virtual void acquire();
 125
 126     /**
 127      * Increment the count, unblocking one thread if count is positive.
 128      *
 129      * @see Lockable::release()
 130      */
 131     virtual void release();
 132
 133   };
 134
 135
 136 } // namespace ZThread
 137
 138 #endif // __ZTCOUNTINGSEMAPHORE_H__