new home directory
[feisty_meow.git] / nucleus / 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