aboutsummaryrefslogtreecommitdiff
path: root/src/ito.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/ito.h98
1 files changed, 98 insertions, 0 deletions
diff --git a/src/ito.h b/src/ito.h
new file mode 100644
index 0000000..01253f5
--- /dev/null
+++ b/src/ito.h
@@ -0,0 +1,98 @@
1#ifndef ITO_H
2#define ITO_H
3
4#include <pthread.h>
5
6namespace Bu
7{
8 /**
9 * Simple thread class. This wraps the basic pthread (posix threads) system in
10 * an object oriented sort of way. It allows you to create a class with
11 * standard member variables and callable functions that can be run in it's own
12 * thread, one per class instance.
13 *@author Mike Buland
14 */
15 class Ito
16 {
17 public:
18 /**
19 * Construct an Ito thread.
20 */
21 Ito();
22
23 /**
24 * Destroy an Ito thread.
25 */
26 virtual ~Ito();
27
28 /**
29 * Begin thread execution. This will call the overridden run function,
30 * which will simply execute in it's own thread until the function exits,
31 * the thread is killed, or the thread is cancelled (optionally). The
32 * thread started in this manner has access to all of it's class variables,
33 * but be sure to protect possible multiple-access with ItoMutex objects.
34 *@returns True if starting the thread was successful. False if something
35 * went wrong and the thread has not started.
36 */
37 bool start();
38
39 /**
40 * Forcibly kill a thread. This is not generally considered a good thing to
41 * do, but in those rare cases you need it, it's invaluable. The problem
42 * with stopping (or killing) a thread is that it stops it the moment you
43 * call stop, no matter what it's doing. The object oriented approach to
44 * this will help clean up any class variables that were used, but anything
45 * not managed as a member variable will probably create a memory leak type
46 * of situation. Instead of stop, consider using cancel, which can be
47 * handled by the running thread in a graceful manner.
48 *@returns True if the thread was stopped, false otherwise. When this
49 * function returns the thread may not have stopped, to ensure that the
50 * thread has really stopped, call join.
51 */
52 bool stop();
53
54 /**
55 * The workhorse of the Ito class. This is the function that will run in
56 * the thread, when this function exits the thread dies and is cleaned up
57 * by the system. Make sure to read up on ItoMutex, ItoCondition, and
58 * cancel to see how to control and protect everything you do in a safe way
59 * within this function.
60 *@returns I'm not sure right now, but this is the posix standard form.
61 */
62 virtual void *run()=0;
63
64 /**
65 * Join the thread in action. This function performs what is commonly
66 * called a thread join. That is that it effectively makes the calling
67 * thread an the Ito thread contained in the called object one in the same,
68 * and pauses the calling thread until the called thread exits. That is,
69 * when called from, say, your main(), mythread.join() will not return until
70 * the thread mythread has exited. This is very handy at the end of
71 * programs to ensure all of your data was cleaned up.
72 *@returns True if the thread was joined, false if the thread couldn't be
73 * joined, usually because it isn't running to begin with.
74 */
75 bool join();
76
77 private:
78 pthread_t ptHandle; /**< Internal handle to the posix thread. */
79 int nHandle; /**< Numeric handle to the posix thread. */
80
81 protected:
82 /**
83 * This is the hidden-heard of the thread system. While run is what the
84 * user gets to override, and everything said about it is true, this is
85 * the function that actually makes up the thread, it simply calls the
86 * run member function in an OO-friendly way. This is what allows us to
87 * use member variables from within the thread itself.
88 *@param Should always be this.
89 *@returns This is specified by posix, I'm not sure yet.
90 */
91 static void *threadRunner( void *pThread );
92
93 void yield();
94
95 };
96}
97
98#endif