core/library/processes/thread_cabinet.h

   1 #ifndef THREAD_CABINET_CLASS
   2 #define THREAD_CABINET_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : thread_cabinet                                                    *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2000-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 // forward.
  19 #include "ethread.h"
  20
  21 #include <basis/mutex.h>
  22 #include <structures/roller.h>
  23 #include <structures/set.h>
  24 #include <structures/unique_id.h>
  25
  26 namespace processes {
  27
  28 class thread_amorph;
  29
  30 //! Manages a collection of threads.
  31 /*!
  32   The thread cabinet allows one to corral a bunch of threads in one place
  33   and treat them as a group if necessary.
  34 */
  35
  36 class thread_cabinet
  37 {
  38 public:
  39   thread_cabinet();
  40   virtual ~thread_cabinet();
  41
  42   DEFINE_CLASS_NAME("thread_cabinet");
  43
  44   structures::unique_int add_thread(ethread *to_add, bool start_it, void *parm);
  45     //!< adds a thread to be managed by the thread_cabinet.
  46     /*!< the thread cabinet takes over responsibility for the thread "to_add".
  47     if "start_it" is true, then the thread is started.  otherwise it is
  48     left in whatever state it was in.  the "parm" is passed to the thread's
  49     start() method. */
  50
  51   bool zap_thread(const structures::unique_int &to_whack);
  52     //!< removes the thread with the id "to_whack".
  53     /*!< if it's found and stopped and removed, true is returned.  note that
  54     if the thread is found, then this will wait until the thread exits before
  55     whacking it. */
  56
  57   bool cancel_thread(const structures::unique_int &to_cancel);
  58     //!< shuts down the thread "to_cancel" as quickly as possible.
  59     /*!< this calls the cancel() method on the thread "to_cancel", which tells
  60     the thread to stop as soon as possible.  once it has stopped, the
  61     clean_debris() method will throw it and other stopped threads out. */
  62
  63   int threads() const;  //!< number of threads being managed here.
  64
  65   structures::int_set thread_ids() const;
  66     //!< returns the identifiers of all threads managed by this object.
  67
  68   bool any_running() const;
  69     //!< returns true if any threads are currently running.
  70
  71   void start_all(void *pointer);
  72     //!< cranks up any threads that are not already running.
  73     /*!< the "pointer" will be provided to any threads that are started. */
  74
  75   void cancel_all();
  76     //!< signals to all threads that they should exit as soon as possible.
  77     /*!< this does not actually wait for them to exit. */
  78
  79   void stop_all();
  80     //!< makes all of the threads quit.
  81     /*!< they are cleaned up after they have stopped running also.  any
  82     attempts to add threads while this method is operating will be rejected. */
  83
  84   ethread *get_thread(int index);
  85     //!< this returns the thread at "index" in our list.
  86     /*!< note that this is not safe to use if other threads could be removing
  87     threads from the cabinet or calling clean_debris(). */
  88
  89   void clean_debris();
  90     //!< clean out threads that have finished.
  91     /*!< note that if threads were added to the list without starting them,
  92     then these get cleaned out also. */
  93
  94 private:
  95   basis::mutex *_lock;  //!< synchronizes our thread list.
  96   thread_amorph *_threads;  //!< the list of threads we're managing.
  97   structures::int_roller *_next_id;  //!< the id to be assigned to the next thread.
  98   int _no_additions;  //!< true if we're not allowed to add threads currently.
  99 };
 100
 101 } //namespace.
 102
 103 #endif
 104