Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members

CascadeThread Class Reference

an easy to use thread class More...

#include <cascade/interthread/CascadeThread.h>

Inheritance diagram for CascadeThread:

CascadeObject List of all members.

Public Member Functions

 CascadeThread ()
virtual ~CascadeThread ()
bool Start (bool bDetached=false)
bool WaitUntilFinished ()
bool Detach ()
u32 GetThreadID ()
void SetName (const char *pName)
void GetName (char *pBuff, u32 nBuffLen)
bool SetRealtimePriority (int nPriority)
bool GetRealtimePriority (int &nRealtimePriorityToSet)
bool SetNonRealtime ()
bool IsRealtimeThread ()
 deterimines whether or not a thread is a real-time thread

Static Public Member Functions

static void Sleep (u32 nMilliseconds)
static u32 GetCurrentThreadID ()
static void GetValidRealtimePriorityRange (int &lowest, int &highest)
static bool IsValidRealtimePriority (int nPriority)

Protected Member Functions

virtual void ThreadProc ()=0

Detailed Description

an easy to use thread class

Skip the description

CascadeThread provides easy to use access to posix threads.

class CascadeThread

Constructor & Destructor Documentation

CascadeThread::CascadeThread (   ) 
 

the default constructor - lightweight

This default constructor is lightweight.

virtual CascadeThread::~CascadeThread (   )  [virtual]
 

destructor

The destructor.

Note:
You must NEVER destruct a CascadeThread derived class if the thread has been started detached. It will result in a segmentation fault.
See also:
Start()
Note:
You must never destruct a non-detached CascadeThread until it is finished. (i.e. ALWAYS call WaitUntilFinished() on non-detached threads BEFORE destructing).
See also:
WaitUntilFinished()

Member Function Documentation

bool CascadeThread::Detach (   ) 
 

Detaches a thread

Detach() detaches the thread, meaning that it will delete itself upon completion. This is a very dangerous function. You must not reference or cause this thread object to be referenced once you call Detach(). Once Detach() is called the thread could delete itself at any point in time. You may not call WaitUntilFinished() or any other function. (Don't reference this thread after calling this function!!!)

Returns:
whether or not the detachment succeeded.
Note:
If Detach() is called on a thread object that is not currently running the object will be deleted immediately!! (equivalent to delete this).

static u32 CascadeThread::GetCurrentThreadID (   )  [static]
 

gets the thread id of the calling thread.

GetCurrentThreadID() gets the thread ID of the calling thread, (not this). Note that GetCurrentThreadID() is static.

Returns:
the current thread ID or 0 on error

void CascadeThread::GetName (  char *  pBuff,
u32  nBuffLen
) 
 

gets the name of the thread

GetName() fills *pBuff with the name of the thread.

Parameters:
pBuff the buffer to receive the null-terminated thread name
nBuffLen the length of pBuff
See also:
SetName()

bool CascadeThread::GetRealtimePriority (  int &  nRealtimePriorityToSet  ) 
 

gets the realtime thread priority

GetRealtimePriority() sets nRealtimePriorityToSet with the current real time priority of the thread, returning true if successful, false if the thread is not real-time scheduled. If GetRealtimePriority() returns false, nRealtimePriorityToSet is left untouched.

Parameters:
nRealtimePriorityToSet a reference parameter to receive the real-time priority
Returns:
true if successful, false if the thread is not real-time scheduled
See also:
SetRealtimePriority(), IsRealtimeThread()

u32 CascadeThread::GetThreadID (   ) 
 

gets the thread id of this thread.

GetThreadID() gets the thread ID of the this thread.

Returns:
the current thread ID or 0 if this is not running

static void CascadeThread::GetValidRealtimePriorityRange (  int &  lowest,
int &  highest
)  [static]
 

gets the valid range for real-time thread priorities

GetValidRealtimePriorityRange() sets lowest and highest with the lowest and highest priorities available for setting with SetRealtimePriority(). Note that lowest may be > highest, indicating the lower the number the higher the priority.

Parameters:
lowest a reference paramter to receive the lowest real-time thread priority
highest a reference paramter to receive the highest real-time thread priority
See also:
SetRealtimePriority(), IsValidRealtimePriority()

bool CascadeThread::IsRealtimeThread (   )  [inline]
 

deterimines whether or not a thread is a real-time thread

static bool CascadeThread::IsValidRealtimePriority (  int  nPriority  )  [static]
 

determines whether or not a priority is a valid real-time priority

IsValidRealtimePriority() returns true if nPriority represents a valid realtime thread priority, false otherwise - it uses GetValidRealtimePriorityRange automatically taking into account proper range ordering

Parameters:
nPriority the priority to test
Returns:
whether or not the priority is a valid real-time priority
See also:
SetRealtimePriority(), IsValidRealtimePriority()

void CascadeThread::SetName (  const char *  pName  ) 
 

sets the name for the thread

SetName() sets the name of the thread. This name is associated with the thread, but not otherwise used. It can be useful for debugging purposes.

Parameters:
pName the name of the thread
See also:
GetName()

bool CascadeThread::SetNonRealtime (   ) 
 

sets the thread to have non-realtime priority

SetNonRealtime() may be used to turn a real-time thread into a non-real time thread. It returns true if successful, false otherwise.

Returns:
whether or not the thread was successfully set to non-real-time
See also:
SetRealtimePriority(), IsRealtimeThread()

bool CascadeThread::SetRealtimePriority (  int  nPriority  ) 
 

sets the realtime thread priority

SetRealtimePriority() sets the scheduling policy for this thread to use real-time scheduling (currently SCHED_RR) and sets the priority of the thread to nPriority returning true if successful or false otherwise. Only processes with SuperUser priviliges can set a thread to have a realtime priority.

nPriority must be in the range described by GetValidRealtimePriorityRange().

The new priority will not take effect until the thread is started. If the thread is already running, the new priority will take effect immediately.

Failure (for non super-users) occurs immediately on running threads, and only when Start() is called for non-started threads.

Parameters:
nPriority the priority of the thread
Returns:
whether or not the priority was set succesfully
See also:
GetValidRealtimePriorityRange()

GetRealtimePriority(), SetNonRealtime(), IsRealtimeThread()

static void CascadeThread::Sleep (  u32  nMilliseconds  )  [static]
 

causes the calling thread to sleep

Sleep() causes the calling thread, (not this) to sleep for nMilliseconds. Note that Sleep() is static.

Parameters:
nMilliseconds the number of milliseconds to sleep for

bool CascadeThread::Start (  bool  bDetached = false  ) 
 

starts the thread

Start() starts the thread returning true if successful, false otherwise. if the thread is already running, Start() will return true!

By default a thread is not detached, it can be joined with a call to WaitUntilFinished(). If a thread is detached, this must NO LONGER be used after Start(true) is called. the this pointer will be auto-deleted if the thread is detached. WaitUntilFinished() must not be called on detached threads.

Start threads like this:

            NON-DETACHED (DEFAULT):
            { CascadeThread thread; thread.Start(); ... thread.WaitUntilFinished(); } // must WaitUntilFinished() before destruction!
            or
            { CascadeThread * pThread = new CascadeThread;  pThread->Start(); pThread->WaitUntilFinished(); delete pThread; }

            DETACHED:
            (new CascadeThread)->Start(true);
            or CascadeThread * pThread = new CascadeThread; pThread->Start(true); // do not use pThread any more after Start(true)

Parameters:
bDetached whether or not the thread should be started detached
Returns:
whether or not the thread start was successful
Note:
On stacksizes: A thread in LinuxThreads starts out with a stack of 4K which will dynamically grow to up to 2Mb. The LinuxThreads author recommends against specifying an initial stack size even though posix allows it because your value will be adjusted as soon as you blow your stack anyway. Therefore we provide no access to thread stack sizes.
See also:
WaitUntilFinished()

virtual void CascadeThread::ThreadProc (   )  [protected, pure virtual]
 

the entry point to your thread

This is the most important function in this class. It is the thread entry point and must be overridden by subclasses to gain control.

bool CascadeThread::WaitUntilFinished (   ) 
 

waits until a thread is finished

WaitUntilFinished() causes the calling thread to block until this thread finishes. WaitUntilFinished() returns true if successful, false if unsuccessful. There are two cases where WaitUntilFinished may return false. Both cases are illegal

            case 1 - a thread tries to wait on itself.
            case 2 - two distinct other threads call WaitUntilFinished on the same thread
                     at the same time (only one thread is allowed to wait for another thread to
                     finish at a time).
Returns:
whether or not the wait was successful
See also:
Start()

The documentation for this class was generated from the following file:
Generated on Sun Jul 24 14:27:21 2005 for Cascade Library by  doxygen 1.4.1