OpenThreads::Thread Class Referenceabstract

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

`#include <Thread>`

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 ()
size_t | 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 (const Affinity &affinity)

## Static Public Member Functions

static int | SetConcurrency (int concurrencyLevel)
static int | GetConcurrency ()
static Thread * | CurrentThread ()
static size_t | CurrentThreadId ()
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.

## Member Enumeration Documentation

## ThreadPolicy

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

## ThreadPriority

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

## Thread()

OpenThreads::Thread::Thread | ( |  | ) |

Constructor

Referenced by CurrentThread(), and ThreadPrivateActions.

## ~Thread()

virtual OpenThreads::Thread::~Thread | ( |  | ) |

virtual

Destructor

## Member Function Documentation

## cancel()

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.

## cancelCleanup()

virtual void OpenThreads::Thread::cancelCleanup | ( |  | ) |

inline virtual

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.

## CurrentThread()

Thread * OpenThreads::Thread::CurrentThread | ( |  | ) |

static

Return a pointer to the current running thread, returns NULL for a non OpenThreads thread.

References Thread().

## CurrentThreadId()

size_t OpenThreads::Thread::CurrentThreadId | ( |  | ) |

static

Return the id of the current thread

Referenced by osg::GraphicsContext::isCurrent().

## detach()

int OpenThreads::Thread::detach | ( |  | ) |

Detach the thread from the calling process.

Returns
  0 if normal, -1 if errno set, errno code otherwise.

## GetConcurrency()

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)

## getImplementation()

void * OpenThreads::Thread::getImplementation | ( |  | ) |

inline

## GetMasterPriority()

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.

## getProcessId()

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.

## getSchedulePolicy()

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.

## getSchedulePriority()

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.

## getStackSize()

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.

## getThreadId()

size_t OpenThreads::Thread::getThreadId | ( |  | ) |

Get a unique thread id. This id is monotonically increasing.

Returns
  a unique thread identifier

## Init()

void OpenThreads::Thread::Init | ( |  | ) |

static

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

## isRunning()

bool OpenThreads::Thread::isRunning | ( |  | ) |

Query the thread's running status

Returns
  true if running, false if not.

## join()

int OpenThreads::Thread::join | ( |  | ) |

Join the calling process with the thread

Returns
  0 if normal, -1 if errno set, errno code otherwise.

## microSleep()

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.

## printSchedulingInfo()

void OpenThreads::Thread::printSchedulingInfo | ( |  | ) |

Print the thread's scheduling information to stdout.

## run()

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::GraphicsThread, osg::OperationThread, osgDB::DatabasePager::DatabaseThread, and osgDB::ImagePager::ImageThread.

## setCancelModeAsynchronous()

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.

## setCancelModeDeferred()

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.

## setCancelModeDisable()

int OpenThreads::Thread::setCancelModeDisable | ( |  | ) |

Disable thread cancellation altogether. Thread::cancel() has no effect.

Returns
  0 if normal, -1 if errno set, errno code otherwise.

## SetConcurrency()

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.

## setProcessorAffinity()

int OpenThreads::Thread::setProcessorAffinity | ( | const Affinity & | affinity | ) |

Set the Thread's processor affinity to all, a single CPU or multiple CPU's This call must be made before start() or startThread() and has no effect after the thread has been running. Returns 0 on success, implementation's error on failure, or -1 if ignored.

## setSchedulePolicy()

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.

## setSchedulePriority()

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 implementation (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.

## setStackSize()

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.

## start()

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.

## startThread()

int OpenThreads::Thread::startThread | ( |  | ) |

## testCancel()

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.

## YieldCurrentThread()

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 Symbol Documentation

## ThreadPrivateActions

friend class ThreadPrivateActions

friend

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

References Thread(), and ThreadPrivateActions.

Referenced by ThreadPrivateActions.

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

- Thread