class Thread

base class used to derive all threads of execution. More...

Contains pure virtuals
Definition#include <thread.h>
Inherited byTCPSession, SocketService
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Members

Protected Members


Detailed Description

Every thread of execution in an application is created by deriving a unique class from the Thread class and by implementing the Run method. The base Thread class supports encapsulation of the generic threading methods implemented on various target operating systems. This includes the ability to start and stop threads in a synchronized and controllable manner, the ability to specify thread execution priority, and thread specific "system call" wrappers, such as for sleep and yield. A thread exception is thrown if the thread cannot be created.

void Run (void)
[protected pure virtual]

All threads execute by deriving the Run method of Thread. This method is called after Initial to begin normal operation of the thread. If the method terminates, then the thread will also terminate after notifying it's parent and calling it's Final() method.

See also: Initial

void First (void)
[protected virtual]

This method is called for the very first instance of a new thread being created in a multi-threaded application. Hence, it is only called once, and by the derived Thread class that happens to be created first.

void Final (void)
[protected virtual]

A thread that is self terminating, either by invoking Exit() or leaving it's Run(), will have this method called. It can be used to self delete the current object assuming the object was created with new on the heap rather than stack local, hence one may often see Final defined as "delete this" in a derived thread class. A Final method, while running, cannot be terminated or cancelled by another thread.

See also: Exit, Run

void Initial (void)
[protected virtual]

The initial method is called by a newly created thread when it starts execution. This method is ran with deferred cancellation disabled by default. The Initial method is given a seperate handler so that it can create temporary objects on it's own stack frame, rather than having objects created on Run() that are only needed by startup and yet continue to consume stack space.

See also: Run

void * getExtended (void)
[protected virtual]

Since getParent() and getThread() only refer to an object of the Thread "base" type, this virtual method can be replaced in a derived class with something that returns data specific to the derived class that can still be accessed through the pointer returned by getParent() and getThread().

Returns: pointer to derived class specific data.

void Notify (Thread *th)
[protected virtual]

When a thread terminates, it now sends a notification message to the parent thread which created it. The actual use of this notification is left to be defined in a derived class.

Parameters:
ththe thread that has terminated.

inline void SignalParent (signo_t signo)
[protected]

In the Posix version of Common C++, this can be used to send a signal into the parent thread of the current object.

Parameters:
signoa posix signal id.

inline void SignalMain (signo_t signo)
[protected]

In the Posix version of Common C++, this can be used to send a signal into the nain application thread.

Parameters:
signoa posix signal id.

void OnTimer (void)
[protected virtual]

A derivable method to call when a SIGALRM is being delivered to a specific thread.

void OnHangup (void)
[protected virtual]

A derived method to handle hangup events being delivered to a specific thread.

void OnException (void)
[protected virtual]

A derived method to call when a SIGABRT is being delivered to a specific thread.

void OnDisconnect (void)
[protected virtual]

A derived method to call when a SIGPIPE is being delivered to a specific thread.

void OnPolling (void)
[protected virtual]

A derived method to handle asynchronous I/O requests delivered to the specified thread.

void OnSignal (int signo)
[protected virtual]

A derivable method to call for delivering a signal event to a specified thread.

Parameters:
signoposix signal id.

inline void Sleep (timeout_t msec)
[protected]

A thread-safe sleep call. On most Posix systems, "sleep()" is implimented with SIGALRM making it unusable from multipe threads. Pthread libraries often define an alternate "sleep" handler such as usleep(), nanosleep(), or nap(), that is thread safe, and also offers a higher timer resolution.

Parameters:
msectimeout in milliseconds.

inline void Exit (void)
[protected]

Used to properly exit from a Thread derived Run() or Initial() method. Terminates execution of the current thread and calls the derived classes Final() method.

void setTimer (timeout_t timer)
[protected]

Used to specify a timeout event that can be delivered to the current thread via SIGALRM. When the timer expires, the OnTimer() method is called for the thread. At present, only one thread timer can be active at any given time. On some operating systems (including Linux) a timer can be active on each thread.

Parameters:
timertimeout in milliseconds.

timeout_t getTimer (void)
[protected]

Gets the time remaining for the current threads timer before it expires.

Returns: time remaining before timer expires in milliseconds.

void endTimer (void)
[protected]

Terminates the timer before the timeout period has expired. This prevents the timer from sending it's SIGALRM and makes the timer available to other threads.

void WaitSignal (signo_t signo)
[protected]

Used to wait on a Posix signal from another thread. This can be used as a crude rondevious/synchronization method between threads.

Parameters:
signoa posix signal id.

void Yield (void)
[protected]

Yeilds the current thread's CPU time slice to allow another thread to begin immediate execution.

void setCancel (thread_cancel_t mode)
[protected]

Sets thread cancellation mode. Threads can either be set immune to termination (THREAD_CANCEL_DISABLED), can be set to terminate when reaching specific "thread cancellation points" (THREAD_CANCEL_DEFERRED) or immediately when Terminate is requested (THREAD_CANCEL_IMMEDIATE).

Parameters:
modefor cancellation of the current thread.

void setSuspend (thread_suspend_t mode)
[protected]

Sets the thread's ability to be suspended from execution. The thread may either have suspend enabled (THREAD_SUSPEND_ENABLE) or disabled (THREAD_SUSPEND_DISABLE).

Parameters:
modefor suspend.

void setSignal (int signo, bool mode)
[protected]

Used to enable or disable a signal within the current thread.

Parameters:
signoposix signal id.
activeset to true to enable.

void Terminate (void)
[protected]

Used by another thread to terminate the current thread. Termination actually occurs based on the current setCancel() mode. When the current thread does terminate, control is returned to the requesting thread. Terminate() should always be called at the start of any destructor of a class derived from Thread to assure the remaining part of the destructor is called without the thread still executing.

Thread (bool flag)

This is actually a special constructor that is used to create a thread "object" for the current execution context when that context is not created via an instance of a derived Thread object itself. This constructor does not support First.

Parameters:
boolused if the main "thread" of the application.

Thread (Semaphore *start = NULL, int pri = 0, size_t stack = 0)

When a thread object is contructed, a new thread of execution context is created. This constructor allows basic properties of that context (thread priority, stack space, etc) to be defined. The starting condition is also specified for whether the thread is to wait on a semaphore before begining execution or wait until it's start method is called.

Parameters:
startsemaphore to wait before executing thread.
prithread base priority relative to it's parent.
stackspace as needed in some implementations.

Thread (const Thread &th)

A thread of execution can also be specified by cloning an existing thread. The existing thread's properties (cancel mode, priority, etc), are also duplicated.

Parameters:
thcurrently executing thread object to clone.

~Thread ()
[virtual]

The thread destructor should clear up any resources that have been allocated by the thread. The desctructor of a derived thread should begin with Terminate() and is presumed to then execute within the context of the thread causing terminaton.

int Start (Semaphore *start = NULL)

When a new thread is created, it does not begin immediate execution. This is because the derived class virtual tables are not properly loaded at the time the C++ object is created within the constructor itself, at least in some compiler/system combinations. The thread can either be told to wait for an external semaphore, or it can be started directly after the constructor completes by calling the Start() method.

Parameters:
startoptional starting semaphore to alternately use.

Returns: error code if execution fails.

inline Thread * getParent (void)

Gets the pointer to the Thread class which created the current thread object.

Returns: a Thread *, or "(Thread *)this" if no parent.

inline void SignalThread (int signo)

Delivers a Posix signal to the current thread.

Parameters:
signoa posix signal id.

inline void Suspend (void)

Suspends execution of the selected thread. Pthreads do not normally support suspendable threads, so the behavior is simulated with signals. On systems such as Linux that define threads as processes, SIGSTOP and SIGCONT may be used.

inline void Resume (void)

Resumes execution of the selected thread.

inline int getCancel (void)

Used to retrieve the cancellation mode in effect for the selected thread.

Returns: cancellation mode constant.

inline bool isRunning (void)

Verifies if the thread is still running or has already been terminated but not yet deleted.

Returns: true if the thread is still executing.

inline bool isThread (void)

Tests to see if the current execution context is the same as the specified thread object.

Returns: true if the current context is this object.

friend void ccxx_sleep (timeout_t msec)

Thread safe sleep call replacement. This is mapped into sleep().

Parameters:
msectimeout in millisecond time range.

friend void suspend (Thread &th)

Suspend the execution of the specified thread.

Parameters:
thspecified thread.

friend void resume (Thread &th)

Resume execution of the specified thread.

Parameters:
thspecified thread.

friend inline void operator++ (Thread &th)

Signal the semaphore that the specified thread is waiting for before beginning execution.

Parameters:
thspecified thread.

friend inline int start (Thread &th, Semaphore *start)

Start execution of a specified thread.

friend void siginstall (int signo)

Install a signal handler for use by threads and the OnSignal() event notification handler.

Parameters:
signoposix signal id.