aboutsummaryrefslogtreecommitdiff
path: root/src/stable/thread.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/stable/thread.h228
1 files changed, 114 insertions, 114 deletions
diff --git a/src/stable/thread.h b/src/stable/thread.h
index ae07665..ca3ab9f 100644
--- a/src/stable/thread.h
+++ b/src/stable/thread.h
@@ -15,120 +15,120 @@
15 15
16namespace Bu 16namespace Bu
17{ 17{
18 subExceptionDecl( ThreadException ); 18 subExceptionDecl( ThreadException );
19 class ThreadId 19 class ThreadId
20 { 20 {
21 friend class Thread; 21 friend class Thread;
22 private: 22 private:
23 ThreadId( pthread_t tId ); 23 ThreadId( pthread_t tId );
24 24
25 public: 25 public:
26 ThreadId(); 26 ThreadId();
27 27
28 bool operator==( const ThreadId &rhs ); 28 bool operator==( const ThreadId &rhs );
29 bool operator!=( const ThreadId &rhs ); 29 bool operator!=( const ThreadId &rhs );
30 30
31 private: 31 private:
32 pthread_t tId; 32 pthread_t tId;
33 }; 33 };
34 34
35 /** 35 /**
36 * Simple thread class. This wraps the basic pthread (posix threads) 36 * Simple thread class. This wraps the basic pthread (posix threads)
37 * system in an object oriented sort of way. It allows you to create a 37 * system in an object oriented sort of way. It allows you to create a
38 * class with standard member variables and callable functions that can be 38 * class with standard member variables and callable functions that can be
39 * run in it's own thread, one per class instance. 39 * run in it's own thread, one per class instance.
40 *@ingroup Threading 40 *@ingroup Threading
41 */ 41 */
42 class Thread 42 class Thread
43 { 43 {
44 public: 44 public:
45 /** 45 /**
46 * Construct an Thread thread. 46 * Construct an Thread thread.
47 */ 47 */
48 Thread(); 48 Thread();
49 49
50 /** 50 /**
51 * Destroy an Thread thread. 51 * Destroy an Thread thread.
52 */ 52 */
53 virtual ~Thread(); 53 virtual ~Thread();
54 54
55 static ThreadId currentThread(); 55 static ThreadId currentThread();
56 ThreadId getId() { return ThreadId( ptHandle ); } 56 ThreadId getId() { return ThreadId( ptHandle ); }
57 57
58 /** 58 /**
59 * Begin thread execution. This will call the overridden run function, 59 * Begin thread execution. This will call the overridden run function,
60 * which will simply execute in it's own thread until the function 60 * which will simply execute in it's own thread until the function
61 * exits, the thread is killed, or the thread is cancelled (optionally). 61 * exits, the thread is killed, or the thread is cancelled (optionally).
62 * The thread started in this manner has access to all of it's class 62 * The thread started in this manner has access to all of it's class
63 * variables, but be sure to protect possible multiple-access with 63 * variables, but be sure to protect possible multiple-access with
64 * ThreadMutex objects. 64 * ThreadMutex objects.
65 * @returns True if starting the thread was successful. False if 65 * @returns True if starting the thread was successful. False if
66 * something went wrong and the thread has not started. 66 * something went wrong and the thread has not started.
67 */ 67 */
68 bool start(); 68 bool start();
69 69
70 /** 70 /**
71 * Forcibly kill a thread. This is not generally considered a good 71 * Forcibly kill a thread. This is not generally considered a good
72 * thing to do, but in those rare cases you need it, it's invaluable. 72 * thing to do, but in those rare cases you need it, it's invaluable.
73 * The problem with stopping (or killing) a thread is that it stops it 73 * The problem with stopping (or killing) a thread is that it stops it
74 * the moment you call stop, no matter what it's doing. The object 74 * the moment you call stop, no matter what it's doing. The object
75 * oriented approach to this will help clean up any class variables 75 * oriented approach to this will help clean up any class variables
76 * that were used, but anything not managed as a member variable will 76 * that were used, but anything not managed as a member variable will
77 * probably create a memory leak type of situation. Instead of stop, 77 * probably create a memory leak type of situation. Instead of stop,
78 * consider using cancel, which can be handled by the running thread in 78 * consider using cancel, which can be handled by the running thread in
79 * a graceful manner. 79 * a graceful manner.
80 *@returns True if the thread was stopped, false otherwise. When this 80 *@returns True if the thread was stopped, false otherwise. When this
81 * function returns the thread may not have stopped, to ensure that the 81 * function returns the thread may not have stopped, to ensure that the
82 * thread has really stopped, call join. 82 * thread has really stopped, call join.
83 */ 83 */
84 bool stop(); 84 bool stop();
85 85
86 /** 86 /**
87 * Join the thread in action. This function performs what is commonly 87 * Join the thread in action. This function performs what is commonly
88 * called a thread join. That is that it effectively makes the calling 88 * called a thread join. That is that it effectively makes the calling
89 * thread an the Thread thread contained in the called object one in the 89 * thread an the Thread thread contained in the called object one in the
90 * same, and pauses the calling thread until the called thread exits. 90 * same, and pauses the calling thread until the called thread exits.
91 * That is, when called from, say, your main(), mythread.join() will 91 * That is, when called from, say, your main(), mythread.join() will
92 * not return until the thread mythread has exited. This is very handy 92 * not return until the thread mythread has exited. This is very handy
93 * at the end of programs to ensure all of your data was cleaned up. 93 * at the end of programs to ensure all of your data was cleaned up.
94 *@returns True if the thread was joined, false if the thread couldn't 94 *@returns True if the thread was joined, false if the thread couldn't
95 * be joined, usually because it isn't running to begin with. 95 * be joined, usually because it isn't running to begin with.
96 */ 96 */
97 bool join(); 97 bool join();
98 98
99 private: 99 private:
100 pthread_t ptHandle; /**< Internal handle to the posix thread. */ 100 pthread_t ptHandle; /**< Internal handle to the posix thread. */
101 101
102 protected: 102 protected:
103 /** 103 /**
104 * The workhorse of the Thread class. This is the function that will 104 * The workhorse of the Thread class. This is the function that will
105 * run in the thread, when this function exits the thread dies and is 105 * run in the thread, when this function exits the thread dies and is
106 * cleaned up by the system. Make sure to read up on Bu::Mutex, 106 * cleaned up by the system. Make sure to read up on Bu::Mutex,
107 * Bu::Condition, and the Bu::Synchro* classes to see how to control 107 * Bu::Condition, and the Bu::Synchro* classes to see how to control
108 * and protect everything you do in a safe way within this function. 108 * and protect everything you do in a safe way within this function.
109 *@returns I'm not sure right now, but this is the posix standard form. 109 *@returns I'm not sure right now, but this is the posix standard form.
110 */ 110 */
111 virtual void run()=0; 111 virtual void run()=0;
112 112
113 /** 113 /**
114 * Gives up some cpu-time in the currently running thread. If a thread 114 * Gives up some cpu-time in the currently running thread. If a thread
115 * is working hard, but you want to give other threads on the system 115 * is working hard, but you want to give other threads on the system
116 * some time to do some work, call yield. 116 * some time to do some work, call yield.
117 */ 117 */
118 void yield(); 118 void yield();
119 119
120 private: 120 private:
121 /** 121 /**
122 * This is the hidden-heart of the thread system. While run is what the 122 * This is the hidden-heart of the thread system. While run is what the
123 * user gets to override, and everything said about it is true, this is 123 * user gets to override, and everything said about it is true, this is
124 * the function that actually makes up the thread, it simply calls the 124 * the function that actually makes up the thread, it simply calls the
125 * run member function in an OO-friendly way. This is what allows us to 125 * run member function in an OO-friendly way. This is what allows us to
126 * use member variables from within the thread itself. 126 * use member variables from within the thread itself.
127 *@param pThread Should always be this. 127 *@param pThread Should always be this.
128 *@returns This is specified by posix, I'm not sure yet. 128 *@returns This is specified by posix, I'm not sure yet.
129 */ 129 */
130 static void *threadRunner( void *pThread ); 130 static void *threadRunner( void *pThread );
131 }; 131 };
132} 132}
133 133
134#endif 134#endif