dep/include/zthread/SynchronousExecutor.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 __ZTSYNCHRONOUSEXECUTOR_H__
  24 #define __ZTSYNCHRONOUSEXECUTOR_H__
  25
  26 #include "zthread/Executor.h"
  27 #include "zthread/Guard.h"
  28 #include "zthread/Mutex.h"
  29 #include "zthread/Thread.h"
  30
  31 namespace ZThread {
  32
  33   /**
  34    * @class SynchronousExecutor
  35    *
  36    * @author Eric Crahen <http://www.code-foo.com>
  37    * @date <2003-07-16T22:33:51-0400>
  38    * @version 2.3.0
  39    *
  40    * A SynchronousExecutor is an Executor which runs tasks using the thread that
  41    * submits the task. It runs tasks serially, one at a time, in the order they
  42    * were submitted to the executor.
  43    *
  44    * @see Executor.
  45    */
  46   class SynchronousExecutor : public Executor {
  47
  48     //! Serialize access
  49     Mutex _lock;
  50
  51     //! Cancellation flag
  52     bool _canceled;
  53
  54     public:
  55
  56     //! Create a new SynchronousExecutor
  57     SynchronousExecutor();
  58
  59     //! Destroy a SynchronousExecutor
  60     virtual ~SynchronousExecutor();
  61
  62     /**
  63      * This operation is not supported by this executor.
  64      */
  65     virtual void interrupt();
  66
  67     /**
  68      * Submit a task to this Executor, blocking the calling thread until the
  69      * task is executed.
  70      *
  71      * @param task Task to be run by a thread managed by this executor
  72      *
  73      * @pre  The Executor should have been canceled prior to this invocation.
  74      * @post The submitted task will be run at some point in the future by this Executor.
  75      *
  76      * @exception Cancellation_Exception thrown if the Executor was canceled prior to
  77      *            the invocation of this function.
  78      *
  79      * @see Executor::execute(const Task& task)
  80      */
  81     virtual void execute(const Task& task);
  82
  83     /**
  84      * @see Cancelable::cancel()
  85      */
  86     virtual void cancel();
  87
  88     /**
  89      * @see Cancelable::cancel()
  90      */
  91     virtual bool isCanceled();
  92
  93     /**
  94      * Block the calling thread until all tasks submitted prior to this invocation
  95      * complete.
  96      *
  97      * @exception Interrupted_Exception thrown if the calling thread is interrupted
  98      *            before the set of tasks being wait for can complete.
  99      *
 100      * @see Executor::wait()
 101      */
 102     virtual void wait();
 103
 104     /**
 105      * Block the calling thread until all tasks submitted prior to this invocation
 106      * complete or until the calling thread is interrupted.
 107      *
 108      * @param timeout - maximum amount of time, in milliseconds, to wait for the
 109      * currently submitted set of Tasks to complete.
 110      *
 111      * @exception Interrupted_Exception thrown if the calling thread is interrupted
 112      *            before the set of tasks being wait for can complete.
 113      *
 114      * @return
 115      *   - <em>true</em> if the set of tasks being wait for complete before
 116      *                   <i>timeout</i> milliseconds elapse.
 117      *   - <em>false</em> othewise.
 118      */
 119     virtual bool wait(unsigned long timeout);
 120
 121
 122   }; /* SynchronousExecutor */
 123
 124 } // namespace ZThread
 125
 126 #endif // __ZTSYNCHRONOUSEXECUTOR_H__