dep/include/zthread/PoolExecutor.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 __ZTPOOLEXECUTOR_H__
  24 #define __ZTPOOLEXECUTOR_H__
  25
  26 #include "zthread/Executor.h"
  27 #include "zthread/CountedPtr.h"
  28 #include "zthread/Thread.h"
  29
  30 namespace ZThread {
  31
  32   namespace { class ExecutorImpl; }
  33
  34   /**
  35    * @class PoolExecutor
  36    *
  37    * @author Eric Crahen <http://www.code-foo.com>
  38    * @date <2003-07-16T22:41:07-0400>
  39    * @version 2.3.0
  40    *
  41    * A PoolExecutor spawns a set of threads that are used to run tasks
  42    * that are submitted in parallel. A PoolExecutor supports the following
  43    * optional operations,
  44    *
  45    * - <em>cancel</em>()ing a PoolExecutor will cause it to stop accepting
  46    *   new tasks.
  47    *
  48    * - <em>interrupt</em>()ing a PoolExecutor will cause the any thread running
  49    *   a task which was submitted prior to the invocation of this function to
  50    *   be interrupted during the execution of that task.
  51    *
  52    * - <em>wait</em>()ing on a PoolExecutor will block the calling thread
  53    *   until all tasks that were submitted prior to the invocation of this function
  54    *   have completed.
  55    *
  56    * @see Executor.
  57    */
  58   class PoolExecutor : public Executor {
  59
  60     //! Reference to the internal implementation
  61     CountedPtr< ExecutorImpl > _impl;
  62
  63     //! Cancellation task
  64     Task _shutdown;
  65
  66   public:
  67
  68     /**
  69      * Create a PoolExecutor
  70      *
  71      * @param n number of threads to service tasks with
  72      */
  73     PoolExecutor(size_t n);
  74
  75     //! Destroy a PoolExecutor
  76     virtual ~PoolExecutor();
  77
  78     /**
  79      * Invoking this function causes each task that had been submitted prior to
  80      * this function to be interrupted. Tasks submitted after the invocation of
  81      * this function are unaffected.
  82      *
  83      * @post Any task submitted prior to the invocation of this function will be
  84      *       run in the context of an interrupted thread.
  85      * @post Any thread already executing a task which was submitted prior to the
  86      *       invocation of this function will be interrupted.
  87      */
  88     virtual void interrupt();
  89
  90     /**
  91      * Alter the number of threads being used to execute submitted tasks.
  92      *
  93      * @param n number of worker threads.
  94      *
  95      * @pre  <i>n</i> must be greater than 0.
  96      * @post <i>n</i> threads will be executing tasks submitted to this executor.
  97      *
  98      * @exception InvalidOp_Exception thrown if the new number of threads
  99      *            <i>n</i> is less than 1.
 100      */
 101     void size(size_t n);
 102
 103     /**
 104      * Get the current number of threads being used to execute submitted tasks.
 105      *
 106      * @return n number of worker threads.
 107      */
 108     size_t size();
 109
 110     /**
 111      * Submit a task to this Executor.
 112      *
 113      * This will not block the calling thread very long. The submitted task will
 114      * be executed at some later point by another thread.
 115      *
 116      * @param task Task to be run by a thread managed by this executor
 117      *
 118      * @pre  The Executor should have been canceled prior to this invocation.
 119      * @post The submitted task will be run at some point in the future by this Executor.
 120      *
 121      * @exception Cancellation_Exception thrown if the Executor was canceled prior to
 122      *            the invocation of this function.
 123      *
 124      * @see PoolExecutor::cancel()
 125      * @see Executor::execute(const Task& task)
 126      */
 127     virtual void execute(const Task& task);
 128
 129     /**
 130      * @see Cancelable::cancel()
 131      */
 132     virtual void cancel();
 133
 134     /**
 135      * @see Cancelable::isCanceled()
 136      */
 137     virtual bool isCanceled();
 138
 139     /**
 140      * Block the calling thread until all tasks submitted prior to this invocation
 141      * complete.
 142      *
 143      * @exception Interrupted_Exception thrown if the calling thread is interrupted
 144      *            before the set of tasks being wait for can complete.
 145      *
 146      * @see Waitable::wait()
 147      */
 148     virtual void wait();
 149
 150     /**
 151      * Block the calling thread until all tasks submitted prior to this invocation
 152      * complete or until the calling thread is interrupted.
 153      *
 154      * @param timeout maximum amount of time, in milliseconds, to wait for the
 155      *                currently submitted set of Tasks to complete.
 156      *
 157      * @exception Interrupted_Exception thrown if the calling thread is interrupted
 158      *            before the set of tasks being wait for can complete.
 159      *
 160      * @return
 161      *   - <em>true</em> if the set of tasks being wait for complete before
 162      *                   <i>timeout</i> milliseconds elapse.
 163      *   - <em>false</em> otherwise.
 164      *
 165      * @see Waitable::wait(unsigned long timeout)
 166      */
 167     virtual bool wait(unsigned long timeout);
 168
 169   }; /* PoolExecutor */
 170
 171
 172 } // namespace ZThread
 173
 174 #endif // __ZTPOOLEXECUTOR_H__
 175
 176
 177
 178