aboutsummaryrefslogtreecommitdiff
path: root/src/ito.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/ito.h63
1 files changed, 33 insertions, 30 deletions
diff --git a/src/ito.h b/src/ito.h
index c062052..4ed2c8b 100644
--- a/src/ito.h
+++ b/src/ito.h
@@ -6,11 +6,12 @@
6namespace Bu 6namespace Bu
7{ 7{
8 /** 8 /**
9 * Simple thread class. This wraps the basic pthread (posix threads) system in 9 * Simple thread class. This wraps the basic pthread (posix threads)
10 * an object oriented sort of way. It allows you to create a class with 10 * system in an object oriented sort of way. It allows you to create a
11 * standard member variables and callable functions that can be run in it's own 11 * class with standard member variables and callable functions that can be
12 * thread, one per class instance. 12 * run in it's own thread, one per class instance.
13 *@author Mike Buland 13 *@author Mike Buland
14 *@ingroup Threading
14 */ 15 */
15 class Ito 16 class Ito
16 { 17 {
@@ -27,24 +28,26 @@ namespace Bu
27 28
28 /** 29 /**
29 * Begin thread execution. This will call the overridden run function, 30 * 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 * which will simply execute in it's own thread until the function
31 * the thread is killed, or the thread is cancelled (optionally). The 32 * exits, the thread is killed, or the thread is cancelled (optionally).
32 * thread started in this manner has access to all of it's class variables, 33 * The thread started in this manner has access to all of it's class
33 * but be sure to protect possible multiple-access with ItoMutex objects. 34 * variables, but be sure to protect possible multiple-access with
34 *@returns True if starting the thread was successful. False if something 35 * ItoMutex objects.
35 * went wrong and the thread has not started. 36 * @returns True if starting the thread was successful. False if
37 * something went wrong and the thread has not started.
36 */ 38 */
37 bool start(); 39 bool start();
38 40
39 /** 41 /**
40 * Forcibly kill a thread. This is not generally considered a good thing to 42 * Forcibly kill a thread. This is not generally considered a good
41 * do, but in those rare cases you need it, it's invaluable. The problem 43 * thing to do, but in those rare cases you need it, it's invaluable.
42 * with stopping (or killing) a thread is that it stops it the moment you 44 * The problem with stopping (or killing) a thread is that it stops it
43 * call stop, no matter what it's doing. The object oriented approach to 45 * the moment you call stop, no matter what it's doing. The object
44 * this will help clean up any class variables that were used, but anything 46 * oriented approach to this will help clean up any class variables
45 * not managed as a member variable will probably create a memory leak type 47 * that were used, but anything not managed as a member variable will
46 * of situation. Instead of stop, consider using cancel, which can be 48 * probably create a memory leak type of situation. Instead of stop,
47 * handled by the running thread in a graceful manner. 49 * consider using cancel, which can be handled by the running thread in
50 * a graceful manner.
48 *@returns True if the thread was stopped, false otherwise. When this 51 *@returns True if the thread was stopped, false otherwise. When this
49 * function returns the thread may not have stopped, to ensure that the 52 * function returns the thread may not have stopped, to ensure that the
50 * thread has really stopped, call join. 53 * thread has really stopped, call join.
@@ -52,11 +55,11 @@ namespace Bu
52 bool stop(); 55 bool stop();
53 56
54 /** 57 /**
55 * The workhorse of the Ito class. This is the function that will run in 58 * The workhorse of the Ito class. This is the function that will run
56 * the thread, when this function exits the thread dies and is cleaned up 59 * in the thread, when this function exits the thread dies and is
57 * by the system. Make sure to read up on ItoMutex, ItoCondition, and 60 * cleaned up by the system. Make sure to read up on ItoMutex,
58 * cancel to see how to control and protect everything you do in a safe way 61 * ItoCondition, and cancel to see how to control and protect
59 * within this function. 62 * everything you do in a safe way within this function.
60 *@returns I'm not sure right now, but this is the posix standard form. 63 *@returns I'm not sure right now, but this is the posix standard form.
61 */ 64 */
62 virtual void *run()=0; 65 virtual void *run()=0;
@@ -64,13 +67,13 @@ namespace Bu
64 /** 67 /**
65 * Join the thread in action. This function performs what is commonly 68 * Join the thread in action. This function performs what is commonly
66 * called a thread join. That is that it effectively makes the calling 69 * 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, 70 * thread an the Ito thread contained in the called object one in the
68 * and pauses the calling thread until the called thread exits. That is, 71 * same, and pauses the calling thread until the called thread exits.
69 * when called from, say, your main(), mythread.join() will not return until 72 * That is, when called from, say, your main(), mythread.join() will
70 * the thread mythread has exited. This is very handy at the end of 73 * not return until the thread mythread has exited. This is very handy
71 * programs to ensure all of your data was cleaned up. 74 * at the end of 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 75 *@returns True if the thread was joined, false if the thread couldn't
73 * joined, usually because it isn't running to begin with. 76 * be joined, usually because it isn't running to begin with.
74 */ 77 */
75 bool join(); 78 bool join();
76 79