dep/include/zthread/Waitable.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 __ZTWAITABLE_H__
  24 #define __ZTWAITABLE_H__
  25
  26 #include "zthread/Exceptions.h"
  27
  28 namespace ZThread {
  29
  30   /**
  31    * @class Waitable
  32    *
  33    * @author Eric Crahen <http://www.code-foo.com>
  34    * @date <2003-07-16T22:16:41-0400>
  35    * @version 2.3.0
  36    *
  37    * The Waitable interface defines a common method of adding generic <i>wait</i> semantics
  38    * to a class.
  39    *
  40    * <b>Waiting</b>
  41    *
  42    * An object implementing the Waitable interface externalizes a mechanism for testing
  43    * some internal condition. Another object may <i>wait()</i>s for a Waitable object;
  44    * in doing so, it wait()s for that condition to become true by blocking the caller
  45    * while the condition is false.
  46    *
  47    * For example, a Condition is Waitable object that extends <i>wait</i> semantics
  48    * so that wait()ing means a thread is blocked until some external stimulus
  49    * specifically performs an operation on the Condition to make its internal condition true.
  50    * (serialization aside)
  51    *
  52    * A Barrier extends <i>wait</i> semantics so that wait()ing mean waiting for other
  53    * waiters, and may include automatically resetting the condition once a wait is complete.
  54    *
  55    * @see Condition
  56    * @see Barrier
  57    * @see Executor
  58    */
  59   class Waitable {
  60   public:
  61
  62     //! Destroy a Waitable object.
  63     virtual ~Waitable() {}
  64
  65     /**
  66      * Waiting on an object will generally cause the calling thread to be blocked
  67      * for some indefinite period of time. The thread executing will not proceed
  68      * any further until the Waitable object releases it unless or an exception
  69      * is thrown.
  70      */
  71     virtual void wait() = 0;
  72
  73     /**
  74      * Waiting on an object will generally cause the calling thread to be blocked
  75      * for some indefinite period of time. The thread executing will not proceed
  76      * any further until the Waitable object releases it unless or an exception
  77      * is thrown.
  78      *
  79      * @param timeout maximum amount of time, in milliseconds, to spend waiting.
  80      *
  81      * @return
  82      *   - <em>true</em> if the set of tasks being wait for complete before
  83      *                   <i>timeout</i> milliseconds elapse.
  84      *   - <em>false</em> othewise.
  85      */
  86     virtual bool wait(unsigned long timeout) = 0;
  87
  88
  89   }; /* Waitable */
  90
  91
  92 } // namespace ZThread
  93
  94 #endif //  __ZTWAITABLE_H__