OpenThreads
Public Types | Public Member Functions | Static Public Member Functions | Friends
OpenThreads::Thread Class Reference

This class provides an object-oriented thread interface. More...

List of all members.

Public Types

enum  ThreadPriority {
  THREAD_PRIORITY_MAX, THREAD_PRIORITY_HIGH, THREAD_PRIORITY_NOMINAL, THREAD_PRIORITY_LOW,
  THREAD_PRIORITY_MIN, THREAD_PRIORITY_DEFAULT
}
 Enumerated Type for thread priority. More...
enum  ThreadPolicy { THREAD_SCHEDULE_FIFO, THREAD_SCHEDULE_ROUND_ROBIN, THREAD_SCHEDULE_TIME_SHARE, THREAD_SCHEDULE_DEFAULT }
 Enumerated Type for thread scheduling policy. More...

Public Member Functions

 Thread ()
 Constructor.
virtual ~Thread ()
 Destructor.
int getThreadId ()
 Get a unique thread id.
size_t getProcessId ()
 Get the thread's process id.
int start ()
 Start the thread.
int startThread ()
int testCancel ()
 Test the cancel state of the thread.
virtual int cancel ()
 Cancel the thread.
int setSchedulePriority (ThreadPriority priority)
 Set the thread's schedule priority.
int getSchedulePriority ()
 Get the thread's schedule priority (if able)
int setSchedulePolicy (ThreadPolicy policy)
 Set the thread's scheduling policy (if able)
int getSchedulePolicy ()
 Get the thread's policy (if able)
int setStackSize (size_t size)
 Set the thread's desired stack size (in bytes).
size_t getStackSize ()
 Get the thread's desired stack size.
void printSchedulingInfo ()
 Print the thread's scheduling information to stdout.
int detach ()
 Detach the thread from the calling process.
int join ()
 Join the calling process with the thread.
int setCancelModeDisable ()
 Disable thread cancelation altogether.
int setCancelModeAsynchronous ()
 Mark the thread to cancel aysncronously on Thread::cancel().
int setCancelModeDeferred ()
 Mark the thread to cancel at the earliest convenience on Thread::cancel() (This is the default)
bool isRunning ()
 Query the thread's running status.
virtual void run ()=0
 Thread's run method.
virtual void cancelCleanup ()
 Thread's cancel cleanup routine, called upon cancel(), after the cancelation has taken place, but before the thread exits completely.
void * getImplementation ()
int setProcessorAffinity (unsigned int cpunum)
 Thread's processor affinity method.

Static Public Member Functions

static int SetConcurrency (int concurrencyLevel)
 Set the concurrency level for a running application.
static int GetConcurrency ()
 Get the concurrency level for a running application.
static ThreadCurrentThread ()
 Return a pointer to the current running thread.
static void Init ()
 Initialize Threading in a program.
static int YieldCurrentThread ()
 Yield the processor.
static ThreadPriority GetMasterPriority ()
 This method will return the ThreadPriority of the master process.
static int microSleep (unsigned int microsec)
 microSleep method, equivilant to the posix usleep(microsec).

Friends

class ThreadPrivateActions
 The Private Actions class is allowed to operate on private data.

Detailed Description

This class provides an object-oriented thread interface.


Member Enumeration Documentation

Enumerated Type for thread scheduling policy.

Enumerator:
THREAD_SCHEDULE_FIFO 

First in, First out scheduling.

THREAD_SCHEDULE_ROUND_ROBIN 

Round-robin scheduling (LINUX_DEFAULT)

THREAD_SCHEDULE_TIME_SHARE 

Time-share scheduling (IRIX DEFAULT)

THREAD_SCHEDULE_DEFAULT 

Default scheduling.

Enumerated Type for thread priority.

Enumerator:
THREAD_PRIORITY_MAX 

The maximum possible priority.

THREAD_PRIORITY_HIGH 

A high (but not max) setting.

THREAD_PRIORITY_NOMINAL 

An average priority.

THREAD_PRIORITY_LOW 

A low (but not min) setting.

THREAD_PRIORITY_MIN 

The miniumum possible priority.

THREAD_PRIORITY_DEFAULT 

Priority scheduling default.


Constructor & Destructor Documentation

OpenThreads::Thread::Thread ( )

Constructor.

virtual OpenThreads::Thread::~Thread ( ) [virtual]

Destructor.


Member Function Documentation

virtual int OpenThreads::Thread::cancel ( ) [virtual]

Cancel the thread.

Equivalent to SIGKILL.

Returns:
0 if normal, -1 if errno set, errno code otherwise.
virtual void OpenThreads::Thread::cancelCleanup ( ) [inline, virtual]

Thread's cancel cleanup routine, called upon cancel(), after the cancelation has taken place, but before the thread exits completely.

This method should be used to repair parts of the thread's data that may have been damaged by a pre-mature cancel. No-op by default.

static Thread* OpenThreads::Thread::CurrentThread ( ) [static]
int OpenThreads::Thread::detach ( )

Detach the thread from the calling process.

Returns:
0 if normal, -1 if errno set, errno code otherwise.
static int OpenThreads::Thread::GetConcurrency ( ) [static]

Get the concurrency level for a running application.

In this case, a return code of 0 means that the application is in default mode. A return code of -1 means that the application is incapable of setting an arbitrary concurrency, because it is a one-to-one execution model (sprocs, linuxThreads)

void* OpenThreads::Thread::getImplementation ( ) [inline]
static ThreadPriority OpenThreads::Thread::GetMasterPriority ( ) [inline, static]

This method will return the ThreadPriority of the master process.

(ie, the one calling the thread->start() methods for the first time) The method will almost certainly return Thread::THREAD_PRIORITY_DEFAULT if Init() has not been called.

Returns:
the Thread::ThreadPriority of the master thread.
size_t OpenThreads::Thread::getProcessId ( )

Get the thread's process id.

This is the pthread_t or pid_t value depending on the threading model being used.

Returns:
thread process id.
int OpenThreads::Thread::getSchedulePolicy ( )

Get the thread's policy (if able)

Note:
seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO will output scheduling information for each thread to stdout.
Returns:
policy if normal, -1 if errno set, errno code otherwise.
int OpenThreads::Thread::getSchedulePriority ( )

Get the thread's schedule priority (if able)

Note:
seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO will output scheduling information for each thread to stdout.
Returns:
0 if normal, -1 if errno set, errno code otherwise.
size_t OpenThreads::Thread::getStackSize ( )

Get the thread's desired stack size.

Returns:
the thread's stack size. 0 indicates that the stack size has either not yet been initialized, or not yet been specified by the application.
int OpenThreads::Thread::getThreadId ( )

Get a unique thread id.

This id is monotonically increasing.

Returns:
a unique thread identifier
static void OpenThreads::Thread::Init ( ) [static]

Initialize Threading in a program.

This method must be called before you can do any threading in a program.

bool OpenThreads::Thread::isRunning ( )

Query the thread's running status.

Returns:
true if running, false if not.
int OpenThreads::Thread::join ( )

Join the calling process with the thread.

Returns:
0 if normal, -1 if errno set, errno code otherwise.
static int OpenThreads::Thread::microSleep ( unsigned int  microsec) [static]

microSleep method, equivilant to the posix usleep(microsec).

This is not strictly thread API but is used so often with threads. It's basically UNIX usleep. Parameter is number of microseconds we current thread to sleep. Returns 0 on succes, non-zero on failure (UNIX errno or GetLastError() will give detailed description.

void OpenThreads::Thread::printSchedulingInfo ( )

Print the thread's scheduling information to stdout.

virtual void OpenThreads::Thread::run ( ) [pure virtual]

Thread's run method.

Must be implemented by derived classes. This is where the action happens.

int OpenThreads::Thread::setCancelModeAsynchronous ( )

Mark the thread to cancel aysncronously on Thread::cancel().

(May not be available with process-level implementations).

Returns:
0 if normal, -1 if errno set, errno code otherwise.
int OpenThreads::Thread::setCancelModeDeferred ( )

Mark the thread to cancel at the earliest convenience on Thread::cancel() (This is the default)

Returns:
0 if normal, -1 if errno set, errno code otherwise.
int OpenThreads::Thread::setCancelModeDisable ( )

Disable thread cancelation altogether.

Thread::cancel() has no effect.

Returns:
0 if normal, -1 if errno set, errno code otherwise.
static int OpenThreads::Thread::SetConcurrency ( int  concurrencyLevel) [static]

Set the concurrency level for a running application.

This method only has effect if the pthreads thread model is being used, and then only when that model is many-to-one (eg. irix). in other cases it is ignored. The concurrency level is only a *hint* as to the number of execution vehicles to use, the actual implementation may do anything it wants. Setting the value to 0 returns things to their default state.

Returns:
previous concurrency level, -1 indicates no-op.
int OpenThreads::Thread::setProcessorAffinity ( unsigned int  cpunum)

Thread's processor affinity method.

This binds a thread to a processor whenever possible. This call must be made before start() or startThread() and has no effect after the thread has been running. In the pthreads implementation, this is only implemented on sgi, through a pthread extension. On other pthread platforms this is ignored. Returns 0 on success, implementation's error on failure, or -1 if ignored.

int OpenThreads::Thread::setSchedulePolicy ( ThreadPolicy  policy)

Set the thread's scheduling policy (if able)

Note:
On some implementations (notably IRIX Sprocs & LinuxThreads) The policy may prohibit the use of SCHEDULE_ROUND_ROBIN and SCHEDULE_FIFO policies - due to their real-time nature, and the danger of deadlocking the machine when used as super-user. In such cases, the command is a no-op.
seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO will output scheduling information for each thread to stdout.
Returns:
0 if normal, -1 if errno set, errno code otherwise.
int OpenThreads::Thread::setSchedulePriority ( ThreadPriority  priority)

Set the thread's schedule priority.

This is a complex method. Beware of thread priorities when using a many-to-many kernel entity implemenation (such as IRIX pthreads). If one is not carefull to manage the thread priorities, a priority inversion deadlock can easily occur (Although the OpenThreads::Mutex & OpenThreads::Barrier constructs have been designed with this senario in mind). Unless you have explicit need to set the schedule pirorites for a given task, it is best to leave them alone.

Note:
some implementations (notably LinuxThreads and IRIX Sprocs) only alow you to decrease thread priorities dynamically. Thus, a lower priority thread will not allow it's priority to be raised on the fly.
seting the environment variable OUTPUT_THREADLIB_SCHEDULING_INFO will output scheduling information for each thread to stdout.
Returns:
0 if normal, -1 if errno set, errno code otherwise.
int OpenThreads::Thread::setStackSize ( size_t  size)

Set the thread's desired stack size (in bytes).

This method is an attribute of the thread and must be called *before* the start() method is invoked.

Note:
a return code of 13 (EACESS) means that the thread stack size can no longer be changed.
Returns:
0 if normal, -1 if errno set, errno code otherwise.
int OpenThreads::Thread::start ( )

Start the thread.

This method will configure the thread, set it's priority, and spawn it.

Note:
if the stack size specified setStackSize is smaller than the smallest allowable stack size, the threads stack size will be set to the minimum allowed, and may be retrieved via the getStackSize()
Returns:
0 if normal, -1 if errno set, errno code otherwise.
int OpenThreads::Thread::startThread ( )
int OpenThreads::Thread::testCancel ( )

Test the cancel state of the thread.

If the thread has been canceled this method will cause the thread to exit now. This method operates on the calling thread.

Returns 0 if normal, -1 if called from a thread other that this.

static int OpenThreads::Thread::YieldCurrentThread ( ) [static]

Yield the processor.

Note:
This method operates on the calling process. And is equivalent to calling sched_yield().
Returns:
0 if normal, -1 if errno set, errno code otherwise.

Friends And Related Function Documentation

friend class ThreadPrivateActions [friend]

The Private Actions class is allowed to operate on private data.


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

osg logo
Generated at Sun Jan 8 2012 13:22:11 for the OpenThreads by doxygen 1.7.4.