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

#include <Thread.h>

Inheritance diagram for OpenThreads::Thread:

Public Types
enum	ThreadPriority { THREAD_PRIORITY_MAX, THREAD_PRIORITY_HIGH, THREAD_PRIORITY_NOMINAL, THREAD_PRIORITY_LOW, THREAD_PRIORITY_MIN, THREAD_PRIORITY_DEFAULT }

enum	ThreadPolicy { THREAD_SCHEDULE_FIFO, THREAD_SCHEDULE_ROUND_ROBIN, THREAD_SCHEDULE_TIME_SHARE, THREAD_SCHEDULE_DEFAULT }

Public Member Functions
	Thread ()

virtual	~Thread ()

int	getThreadId ()

size_t	getProcessId ()

int	start ()

int	startThread ()

int	testCancel ()

virtual int	cancel ()

int	setSchedulePriority (ThreadPriority priority)

int	getSchedulePriority ()

int	setSchedulePolicy (ThreadPolicy policy)

int	getSchedulePolicy ()

int	setStackSize (size_t size)

size_t	getStackSize ()

void	printSchedulingInfo ()

int	detach ()

int	join ()

int	setCancelModeDisable ()

int	setCancelModeAsynchronous ()

int	setCancelModeDeferred ()

bool	isRunning ()

virtual void	run ()=0

virtual void	cancelCleanup ()

void *	getImplementation ()

int	setProcessorAffinity (unsigned int cpunum)

Static Public Member Functions
static int	SetConcurrency (int concurrencyLevel)

static int	GetConcurrency ()

static Thread *	CurrentThread ()

static void	Init ()

static int	YieldCurrentThread ()

static ThreadPriority	GetMasterPriority ()

static int	microSleep (unsigned int microsec)

Friends
class	ThreadPrivateActions

Detailed Description

This class provides an object-oriented thread interface.

Definition at line 49 of file Thread.h.

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

Definition at line 92 of file Thread.h.

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

Definition at line 78 of file Thread.h.

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.

Reimplemented in osg::OperationThread, osgDB::DatabasePager::DatabaseThread, and osgDB::ImagePager::ImageThread.

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.

Definition at line 331 of file Thread.h.

static Thread* OpenThreads::Thread::CurrentThread ( )

static

Return a pointer to the current running thread

Here is the caller graph for this function:

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

Definition at line 333 of file Thread.h.

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.

Definition at line 143 of file Thread.h.

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.

Implemented in osg::OperationThread, osgDB::DatabasePager::DatabaseThread, osgDB::ImagePager::ImageThread, and osg::GraphicsThread.

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.

Definition at line 359 of file Thread.h.

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

osg_head/include/OpenThreads/Thread.h

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