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