Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

Thread Class Reference

#include <Thread.h>

Inheritance diagram for Thread:

List of all members.


Detailed Description

Provides a nice wrapping of pthreads library.

If you need to provide cleanup functions on stop(), cancelled(), etc., you should override the destructor to stop and join so that you can be assured that your cleanup will be called if the thread is auto-destructed by going out of scope

Definition at line 68 of file Thread.h.


Public Types

typedef ThreadNS::Lock Lock
 shorthand for pthread lock wrapper

Public Member Functions

 Thread ()
 constructor, does not start thread by itself (although subclasses may)
virtual ~Thread ()=0
 destructor, will stop and join the thread, but you should override it to do the same if you provide any cleanup functions
virtual void start ()
 requests that the thread be started, if not already running (you need to create a separate instances if you want to run multiple copies)
virtual void interrupt ()
 sends a signal to the thread which will interrupt any sleep calls (and trigger interrupted() to be called within the thread)
virtual void stop ()
 requests that the thread be stopped gracefully, if running.
virtual void kill ()
 sends a SIGUSR1 to the thread, breaking its execution, but still allowing handle_exit (and thus cancelled()) to be called.
virtual void murder ()
 detaches thread and sends SIGSTOP, which immediately halts the thread without any chance for cleanup
virtual void sendSignal (int sig)
 sends a signal to the thread
virtual void * join ()
 blocks calling thread until this Thread has terminated, via one means or another; return value is final return value by the thread
virtual bool isStarted () const
 indicates whether start() has been called (but may be some delay before isRunning() is true...)
virtual bool isRunning () const
 indicates whether the thread is currently alive and running, implies isStarted()
void * getGroup () const
 returns group
void setGroup (void *g)
 assigns group, which will then be inherited by any threads instantiated by this one (the constructor call queries the current thread, no the start() or launch())

Static Public Member Functions

static ThreadgetCurrent ()
 returns the Thread object for the current thread (or NULL for the main thread)
static void initMainThread ()
 should be called before any threads are created to allow some global thread-specific data to be set up
static void releaseMainThread ()
 should be called if you no longer expect to have any threads in use
static void pushNoCancel ()
 should be called whenever a critical section has been entered (i.e. mutex obtained) -- prevents cancel from occurring until popNoCancel() is called
static void popNoCancel ()
 should be called whenever a critical section is left (i.e. mutex released) -- if it was the last one, tests cancellability as well

Protected Member Functions

virtual bool launched ()
 called by launch() when thread is first entered, return false to cancel launch (set returnValue as well if you care)
virtual void * run ()
 called by launch() once the thread has been set up; when this returns, the thread ends, see runloop()
virtual unsigned int runloop ()
 override this as a convenient way to define your thread -- return the number of *micro*seconds to sleep before the next call; return -1U to indicate end of processing
virtual void cancelled ()
 called when handle_exit() is triggered, either by the thread being cancelled, or when run() has returned voluntarily
virtual void testCancel ()
 checks to see if stop() has been called, and if so, will exit the thread (passing through handle_exit() first)
virtual void interrupted ()
 called by handleInterrupt() in target thread following call to interrupt(), assuming thread has not been cancelled (which can intercept the interrupt)

Static Protected Member Functions

static void * launch (void *msg)
 thread entry point -- calls launched() on the thread (as indicated by msg), and then run()
static void handle_launch_signal (int sig)
 indicates kill() has been called (or SIGUSR1 was sent from some other source) while launch() was still running
static void handle_signal (int sig)
 indicates kill() has been called (or SIGUSR1 was sent from some other source)
static void handle_exit (void *th)
 indicates the thread is exiting, either voluntary (run() returned), stop(), or kill() -- calls cancelled() for the thread as indicated by th
static void handleInterrupt (int signal)
 called by SIGALRM signal handler installed by interrupt() just before it posts the corresponding SIGALRM
static void warnSelfUndestructed (void *msg)
 emit a warning that the last thread exited while the self-pointer thread-specific key still exists (need to call releaseMainThread() or handle_exit())

Protected Attributes

struct Threadstorage_t * pt
 stores the actual pthread data fields
bool started
 set to true once start() has been called, set back to false by handle_exit(), or by murder() itself
bool running
 set to true once launch() has been called, set back to false by handle_exit(), or by murder() itself
void * returnValue
 indicates the value to be returned by the thread entry point (and thus passed back to join()) -- set this in runloop() or launched(), overridden by run()'s return value
unsigned int noCancelDepth
 depth of the pushNoCancel() stack
int cancelOrig
 cancel status at root of no-cancel stack (may be no-cancel through and through)
void * group
 indicates a common group of threads, inherited from the thread which created this one, default NULL if created from main thread

Private Member Functions

 Thread (const Thread &r)
 don't call, not a well defined operation
Threadoperator= (const Thread &r)
 don't call, not a well defined operation

Member Typedef Documentation

shorthand for pthread lock wrapper

Definition at line 70 of file Thread.h.


Constructor & Destructor Documentation

Thread::Thread (  ) 

constructor, does not start thread by itself (although subclasses may)

Definition at line 39 of file Thread.cc.

Thread::~Thread (  )  [pure virtual]

destructor, will stop and join the thread, but you should override it to do the same if you provide any cleanup functions

Definition at line 48 of file Thread.cc.

Thread::Thread ( const Thread r  )  [private]

don't call, not a well defined operation


Member Function Documentation

void Thread::start (  )  [virtual]

requests that the thread be started, if not already running (you need to create a separate instances if you want to run multiple copies)

Reimplemented in PollThread.

Definition at line 63 of file Thread.cc.

Referenced by MessageQueueStatusThread::addStatusListener(), MessageReceiver::MessageReceiver(), MessageQueueStatusThread::setMessageQueue(), and PollThread::start().

void Thread::interrupt (  )  [virtual]

sends a signal to the thread which will interrupt any sleep calls (and trigger interrupted() to be called within the thread)

Definition at line 87 of file Thread.cc.

Referenced by stop().

void Thread::stop (  )  [virtual]

requests that the thread be stopped gracefully, if running.

A cancel flag is sent, and the thread will be stopped at next cancel point, defined by whenever testCancel(), or a set of other system functions, are called. See your system's pthread_testcancel() manual page for a list of cancel points.

This function may imply a call to interrupt() on systems which have extremely limited system cancel points. Currently, this consists of only Mac OS X. There is hope that additional cancellation points will be enabled on this system: http://lists.apple.com/archives/darwin-kernel/2004/Jan/msg00032.html

See also:
pushNoCancel(), popNoCancel()

Reimplemented in MessageQueueStatusThread, and MessageReceiver.

Definition at line 95 of file Thread.cc.

Referenced by MessageReceiver::stop(), MessageQueueStatusThread::stop(), PollThread::~PollThread(), and ~Thread().

void Thread::kill (  )  [virtual]

sends a SIGUSR1 to the thread, breaking its execution, but still allowing handle_exit (and thus cancelled()) to be called.

Beware if your thread uses mutual exclusion locks, this can cause the thread to terminate while still holding locks

Definition at line 122 of file Thread.cc.

void Thread::murder (  )  [virtual]

detaches thread and sends SIGSTOP, which immediately halts the thread without any chance for cleanup

Beware if your thread uses mutual exclusion locks, this will cause the thread to terminate while still holding locks.

Definition at line 126 of file Thread.cc.

void Thread::sendSignal ( int  sig  )  [virtual]

sends a signal to the thread

Definition at line 133 of file Thread.cc.

Referenced by interrupt(), kill(), and murder().

void * Thread::join (  )  [virtual]

blocks calling thread until this Thread has terminated, via one means or another; return value is final return value by the thread

Definition at line 146 of file Thread.cc.

Referenced by MessageReceiver::finish(), MessageReceiver::~MessageReceiver(), PollThread::~PollThread(), and ~Thread().

virtual bool Thread::isStarted (  )  const [inline, virtual]

virtual bool Thread::isRunning (  )  const [inline, virtual]

indicates whether the thread is currently alive and running, implies isStarted()

Definition at line 112 of file Thread.h.

Referenced by interrupt(), and sendSignal().

Thread * Thread::getCurrent (  )  [static]

returns the Thread object for the current thread (or NULL for the main thread)

Definition at line 153 of file Thread.cc.

Referenced by handle_exit(), handleInterrupt(), popNoCancel(), pushNoCancel(), Thread(), and warnSelfUndestructed().

void Thread::initMainThread (  )  [static]

should be called before any threads are created to allow some global thread-specific data to be set up

Definition at line 166 of file Thread.cc.

void Thread::releaseMainThread (  )  [static]

should be called if you no longer expect to have any threads in use

Definition at line 173 of file Thread.cc.

void Thread::pushNoCancel (  )  [static]

should be called whenever a critical section has been entered (i.e. mutex obtained) -- prevents cancel from occurring until popNoCancel() is called

Definition at line 267 of file Thread.cc.

Referenced by MessageReceiver::runloop().

void Thread::popNoCancel (  )  [static]

should be called whenever a critical section is left (i.e. mutex released) -- if it was the last one, tests cancellability as well

Definition at line 287 of file Thread.cc.

Referenced by MessageReceiver::runloop().

void* Thread::getGroup (  )  const [inline]

returns group

Definition at line 128 of file Thread.h.

Referenced by Thread().

void Thread::setGroup ( void *  g  )  [inline]

assigns group, which will then be inherited by any threads instantiated by this one (the constructor call queries the current thread, no the start() or launch())

Definition at line 130 of file Thread.h.

virtual bool Thread::launched (  )  [inline, protected, virtual]

called by launch() when thread is first entered, return false to cancel launch (set returnValue as well if you care)

Reimplemented in MessageQueueStatusThread, and MessageReceiver.

Definition at line 134 of file Thread.h.

Referenced by launch(), MessageReceiver::launched(), and MessageQueueStatusThread::launched().

void * Thread::run (  )  [protected, virtual]

called by launch() once the thread has been set up; when this returns, the thread ends, see runloop()

Default implementation repeatedly calls runloop(), usleep(), and testCancel(). If you override, you should also be sure to call testCancel occasionally in order to support stop() If function returns a value, that value overrides returnValue. If cancel occurs, returnValue is used.

Reimplemented in MessageQueueStatusThread, and PollThread.

Definition at line 74 of file Thread.cc.

Referenced by launch().

virtual unsigned int Thread::runloop (  )  [inline, protected, virtual]

override this as a convenient way to define your thread -- return the number of *micro*seconds to sleep before the next call; return -1U to indicate end of processing

Reimplemented in MessageReceiver.

Definition at line 141 of file Thread.h.

Referenced by PollThread::poll(), and run().

virtual void Thread::cancelled (  )  [inline, protected, virtual]

called when handle_exit() is triggered, either by the thread being cancelled, or when run() has returned voluntarily

Reimplemented in MessageQueueStatusThread.

Definition at line 143 of file Thread.h.

Referenced by handle_exit(), and warnSelfUndestructed().

void Thread::testCancel (  )  [protected, virtual]

checks to see if stop() has been called, and if so, will exit the thread (passing through handle_exit() first)

Definition at line 179 of file Thread.cc.

Referenced by handleInterrupt(), run(), PollThread::run(), and MessageQueueStatusThread::run().

void * Thread::launch ( void *  msg  )  [static, protected]

thread entry point -- calls launched() on the thread (as indicated by msg), and then run()

Definition at line 188 of file Thread.cc.

Referenced by start().

void Thread::handle_launch_signal ( int  sig  )  [static, protected]

indicates kill() has been called (or SIGUSR1 was sent from some other source) while launch() was still running

Definition at line 234 of file Thread.cc.

Referenced by launch().

void Thread::handle_signal ( int  sig  )  [static, protected]

indicates kill() has been called (or SIGUSR1 was sent from some other source)

Definition at line 239 of file Thread.cc.

Referenced by launch().

void Thread::handle_exit ( void *  th  )  [static, protected]

indicates the thread is exiting, either voluntary (run() returned), stop(), or kill() -- calls cancelled() for the thread as indicated by th

Definition at line 243 of file Thread.cc.

Referenced by handle_launch_signal(), and launch().

virtual void Thread::interrupted (  )  [inline, protected, virtual]

called by handleInterrupt() in target thread following call to interrupt(), assuming thread has not been cancelled (which can intercept the interrupt)

Reimplemented in PollThread.

Definition at line 157 of file Thread.h.

Referenced by handleInterrupt().

void Thread::handleInterrupt ( int  signal  )  [static, protected]

called by SIGALRM signal handler installed by interrupt() just before it posts the corresponding SIGALRM

tests for thread cancel condition before calling on to interrupted()

Reimplemented in PollThread.

Definition at line 312 of file Thread.cc.

Referenced by interrupt().

void Thread::warnSelfUndestructed ( void *  msg  )  [static, protected]

emit a warning that the last thread exited while the self-pointer thread-specific key still exists (need to call releaseMainThread() or handle_exit())

Definition at line 325 of file Thread.cc.

Referenced by initMainThread().

Thread& Thread::operator= ( const Thread r  )  [private]

don't call, not a well defined operation


Member Data Documentation

struct Threadstorage_t* Thread::pt [read, protected]

stores the actual pthread data fields

Definition at line 167 of file Thread.h.

Referenced by join(), murder(), sendSignal(), start(), stop(), and ~Thread().

bool Thread::started [protected]

set to true once start() has been called, set back to false by handle_exit(), or by murder() itself

Definition at line 169 of file Thread.h.

Referenced by handle_exit(), isStarted(), murder(), sendSignal(), start(), stop(), warnSelfUndestructed(), and ~Thread().

bool Thread::running [protected]

set to true once launch() has been called, set back to false by handle_exit(), or by murder() itself

Definition at line 171 of file Thread.h.

Referenced by handle_exit(), isRunning(), launch(), murder(), sendSignal(), MessageQueueStatusThread::setMessageQueue(), stop(), and warnSelfUndestructed().

void* Thread::returnValue [protected]

indicates the value to be returned by the thread entry point (and thus passed back to join()) -- set this in runloop() or launched(), overridden by run()'s return value

Definition at line 173 of file Thread.h.

Referenced by launch(), run(), and PollThread::run().

unsigned int Thread::noCancelDepth [protected]

depth of the pushNoCancel() stack

Definition at line 175 of file Thread.h.

Referenced by handle_exit(), handleInterrupt(), launch(), popNoCancel(), pushNoCancel(), testCancel(), and warnSelfUndestructed().

int Thread::cancelOrig [protected]

cancel status at root of no-cancel stack (may be no-cancel through and through)

Definition at line 177 of file Thread.h.

Referenced by launch(), popNoCancel(), and pushNoCancel().

void* Thread::group [protected]

indicates a common group of threads, inherited from the thread which created this one, default NULL if created from main thread

Definition at line 180 of file Thread.h.

Referenced by getGroup(), setGroup(), and Thread().


The documentation for this class was generated from the following files:

Tekkotsu v4.0
Generated Thu Nov 22 00:58:44 2007 by Doxygen 1.5.4