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

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. More...

virtual	~Thread ()
	Destructor. More...

int	getThreadId ()
	Get a unique thread id. More...

size_t	getProcessId ()
	Get the thread's process id. More...

int	start ()
	Start the thread. More...

int	startThread ()

int	testCancel ()
	Test the cancel state of the thread. More...

virtual int	cancel ()
	Cancel the thread. More...

int	setSchedulePriority (ThreadPriority priority)
	Set the thread's schedule priority. More...

int	getSchedulePriority ()
	Get the thread's schedule priority (if able) More...

int	setSchedulePolicy (ThreadPolicy policy)
	Set the thread's scheduling policy (if able) More...

int	getSchedulePolicy ()
	Get the thread's policy (if able) More...

int	setStackSize (size_t size)
	Set the thread's desired stack size (in bytes). More...

size_t	getStackSize ()
	Get the thread's desired stack size. More...

void	printSchedulingInfo ()
	Print the thread's scheduling information to stdout. More...

int	detach ()
	Detach the thread from the calling process. More...

int	join ()
	Join the calling process with the thread. More...

int	setCancelModeDisable ()
	Disable thread cancellation altogether. More...

int	setCancelModeAsynchronous ()
	Mark the thread to cancel asynchronously on Thread::cancel(). More...

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

bool	isRunning ()
	Query the thread's running status. More...

virtual void	run ()=0
	Thread's run method. More...

virtual void	cancelCleanup ()
	Thread's cancel cleanup routine, called upon cancel(), after the cancellation has taken place, but before the thread exits completely. More...

void *	getImplementation ()

int	setProcessorAffinity (unsigned int cpunum)
	Thread's processor affinity method. More...

Static Public Member Functions
static int	SetConcurrency (int concurrencyLevel)
	Set the concurrency level for a running application. More...

static int	GetConcurrency ()
	Get the concurrency level for a running application. More...

static Thread *	CurrentThread ()
	Return a pointer to the current running thread. More...

static void	Init ()
	Initialize Threading in a program. More...

static int	YieldCurrentThread ()
	Yield the processor. More...

static ThreadPriority	GetMasterPriority ()
	This method will return the ThreadPriority of the master process. More...

static int	microSleep (unsigned int microsec)
	microSleep method, equivalent to the posix usleep(microsec). More...

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

Detailed Description

This class provides an object-oriented thread interface.

Member Enumeration Documentation

enum OpenThreads::Thread::ThreadPolicy

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.

enum OpenThreads::Thread::ThreadPriority

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 ( )

inlinevirtual

Thread's cancel cleanup routine, called upon cancel(), after the cancellation 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

Return a pointer to the current running thread.

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 ( )

inlinestatic

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: setting 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: setting 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, equivalent 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 success, 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 asynchronously 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 cancellation 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.; setting 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 careful to manage the thread priorities, a priority inversion deadlock can easily occur (Although the OpenThreads::Mutex & OpenThreads::Barrier constructs have been designed with this scenario in mind). Unless you have explicit need to set the schedule priorities for a given task, it is best to leave them alone.

Note: some implementations (notably LinuxThreads and IRIX Sprocs) only allow you to decrease thread priorities dynamically. Thus, a lower priority thread will not allow it's priority to be raised on the fly.; setting 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:

OpenThreads/Thread

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation