Threading

Module Description

The Threading package contains prebuilt, fundamental threading classes, giving you a head-start on building portable, multithreaded applications.

The Threading package includes the runnable classes, the thread attribute classes, and the IOU classes.

For complete information about the Threading package, see the Threads Module User's Guide.

Classes
class	RWCancellation
	Represents an exception that is thrown to cancel a thread. More...
class	RWRunnable
	Handle class for a runnable object, i.e. one that controls an application's threads of execution. More...
class	RWRunnableFunction
	Handle class for functor-based, runnable objects. More...
class	RWRunnableHandle
	Base class from which all runnable object handles derive. More...
class	RWRunnableSelf
	Handle class for a runnable object. More...
class	RWRunnableServer
	Represents a runnable server for executing runnable objects. More...
class	RWRunnableTrap
	Waits for a number of runnables or threads to reach a certain execution state. More...
class	RWServerPool
	Manages a pool of RWRunnableServer instances used to start runnable objects submitted for execution by other threads. More...
class	RWThread
	Handle class for a threaded runnable object. More...
class	RWThreadAttribute
	Encapsulates a set of attributes that define or control thread scheduling and stack allocation. More...
class	RWThreadFunction
	Handle class for functor-based threaded runnable objects. More...
class	RWThreadManager
	Attempts orderly thread shutdown at process exit. More...
class	RWThreadPool
	Manages a pool of RWThread instances used to execute work encapsulated as RWTFunctor<void()> functors. More...
class	RWThreadSelf
	Handle class for a threaded runnable object. More...
class	RWTRunnableIOUFunction< Return >
	Handle class for functor-based runnable objects. More...
class	RWTThreadEscrowImp< Redeemable >
	Multithread-safe implementation of RWTEscrowImp. More...
class	RWTThreadIOUFunction< Return >
	Handle class for functor-based threaded runnable objects. More...
class	RWTThreadLocal< Type >
	Provides thread-local storage with simple by-value semantics. More...

Modules
	rwtMakeRunnableCallback Macros and Functions
	rwtMakeRunnableFunction Macros and Functions
	rwtMakeRunnableGuard Macros and Functions
	rwtMakeRunnableIOUFunction Macros and Functions
	rwtMakeThreadFunction Macros and Functions
	rwtMakeThreadIOU Macros and Functions
	rwtMakeThreadIOUFunction Macros and Functions

Macros
#define	RW_THR_HAS_CONCURRENCY_POLICY
#define	RW_THR_HAS_CONTENTION_SCOPE
#define	RW_THR_HAS_DUAL_PRIORITY
#define	RW_THR_HAS_INHERITANCE_POLICY
#define	RW_THR_HAS_MAX_THREADS
#define	RW_THR_HAS_PARTIAL_STACK_COMMITMENT
#define	RW_THR_HAS_PRIORITY
#define	RW_THR_HAS_PROCESS_SCOPE_PRIORITY
#define	RW_THR_HAS_SCHEDULING_POLICY
#define	RW_THR_HAS_STACK_COMMIT_SIZE
#define	RW_THR_HAS_STACK_RESERVE_SIZE
#define	RW_THR_HAS_START_POLICY
#define	RW_THR_HAS_SUSPEND_RESUME
#define	RW_THR_HAS_SYSTEM_SCOPE_PRIORITY
#define	RW_THR_HAS_TIME_SLICE_QUANTUM
#define	RW_THR_HAS_USER_STACK

Enumerations
enum	RWCompletionState {   RW_THR_PENDING, RW_THR_NORMAL, RW_THR_FAILED, RW_THR_CANCELED,   RW_THR_TERMINATED, RW_THR_UNEXPECTED }
enum	RWConcurrencyPolicy { RW_THR_NO_CHANGE, RW_THR_INCREASE }
enum	RWContentionScope { RW_THR_PROCESS_SCOPE, RW_THR_SYSTEM_SCOPE }
enum	RWExecutionState {   RW_THR_INITIAL, RW_THR_STARTING, RW_THR_RUNNING, RW_THR_INTERRUPTED,   RW_THR_SUSPENDED, RW_THR_SLEEPING, RW_THR_YIELDING, RW_THR_CANCELING,   RW_THR_ABORTING, RW_THR_TERMINATING, RW_THR_EXCEPTION, RW_THR_SERVER_WAIT }
enum	RWInheritancePolicy { RW_THR_INHERIT, RW_THR_EXPLICIT }
enum	RWSchedulingPolicy {   RW_THR_OTHER, RW_THR_TIME_SLICED, RW_THR_TIME_SLICED_FIXED, RW_THR_TIME_SLICED_DYNAMIC,   RW_THR_PREEMPTIVE }
enum	RWStartPolicy { RW_THR_START_RUNNING, RW_THR_START_INTERRUPTED }

Macro Definition Documentation

#define RW_THR_HAS_CONCURRENCY_POLICY

This configuration macro indicates the build environment has support for specifying the concurrency policy. If this macro is not defined, any attempt to set the concurrency policy will fail.

#define RW_THR_HAS_CONTENTION_SCOPE

This configuration macro indicates the build environment has support for specifying the contention scope. If this macro is not defined, any attempt to set the contention scope will fail.

#define RW_THR_HAS_DUAL_PRIORITY

This configuration macro indicates the build environment has support for dual priority threads.

#define RW_THR_HAS_INHERITANCE_POLICY

This configuration macro indicates the build environment has support for specifying the inheritance policy. If this macro is not defined, any attempt to set the inheritance policy will fail.

#define RW_THR_HAS_MAX_THREADS

This configuration macro indicates the build environment has support for determining the maximum number of user threads. If this macro is not defined any attempt to get the maximum thread count will fail.

#define RW_THR_HAS_PARTIAL_STACK_COMMITMENT

This configuration macro indicates the build environment allows partial stack commitment and the stack commit size may be set to a value less than the stack reserve size. If this macro is not defined, then the stack reserve size and stack commit size attributes are mutually exclusive and only one or the other may be set.

#define RW_THR_HAS_PRIORITY

This configuration macro indicates the build environment has support for getting and setting thread priorities. If this macro is not defined, any attempt to get or set the thread priority will fail.

#define RW_THR_HAS_PROCESS_SCOPE_PRIORITY

This configuration macro indicates the build environment has support for specifying process scope priority. If this macro is not defined, any attempt to set the process scope priority will fail.

#define RW_THR_HAS_SCHEDULING_POLICY

This configuration macro indicates the build environment has support for specifying the scheduling policy. If this macro is not defined, any attempt to set the scheduling policy will fail.

#define RW_THR_HAS_STACK_COMMIT_SIZE

This configuration macro indicates the build environment has support for specifying the stack commit size. If this macro is not defined, any attempt to set the stack commit size will fail.

#define RW_THR_HAS_STACK_RESERVE_SIZE

This configuration macro indicates the build environment has support for specifying the stack reserve size. If this macro is not defined, any attempt to set the stack reserve size will fail.

#define RW_THR_HAS_START_POLICY

This configuration macro indicates the build environment has support for specifying a start policy. If this macro is not defined, any attempt to set the start policy will fail.

#define RW_THR_HAS_SUSPEND_RESUME

This configuration macro indicates the build environment has support for specifying the contention scope. If this macro is not defined, any attempt to suspend or resume a thread will fail.

#define RW_THR_HAS_SYSTEM_SCOPE_PRIORITY

This configuration macro indicates the build environment has support for specifying system scope priority. If this macro is not defined, any attempt to set the priority of a system scope thread will fail.

#define RW_THR_HAS_TIME_SLICE_QUANTUM

This configuration macro indicates the build environment has support for specifying the time slice quantum. If this macro is not defined, any attempt to set the time slice quantum will fail.

#define RW_THR_HAS_USER_STACK

This configuration macro indicates the build environment has support for specifying a user stack. If this macro is not defined, any attempt to set a user stack will fail.

Enumeration Type Documentation

enum RWCompletionState

RWCompletionState values describe the completion state of a runnable object. These values are returned by the getCompletionState() member functions of all runnable handles.

Enumerator
RW_THR_PENDING	Runnable has not yet exited because it has not been started or is still active
RW_THR_NORMAL	Exited normally with optional exit code
RW_THR_FAILED	Exited with exception
RW_THR_CANCELED	Exited in response to request for cancellation
RW_THR_TERMINATED	Exited in response to external termination with optional exit code
RW_THR_UNEXPECTED	Exiting due to unhandled exception or signal (currently shutting down process)

enum RWConcurrencyPolicy

RWConcurrencyPolicy values describe whether new kernel threads are created at each new thread creation.

See also

RWThreadAttribute

Enumerator
RW_THR_NO_CHANGE	The creation of a new thread does not force an increase in the effective concurrency supplied by the threads system (no new kernel threads are created).
RW_THR_INCREASE	The creation of a new thread does result in the creation of a new kernel thread to support increased concurrency of execution for the new thread.

enum RWContentionScope

RWContentionScope values describe whether threads contend for processing resources with other threads in the same process or other threads in the system.

See also

RWThreadAttribute

Enumerator
RW_THR_PROCESS_SCOPE	Thread contends for processing resources with other threads in the same process.
RW_THR_SYSTEM_SCOPE	Thread contends for processing resources with other processes in the system.

enum RWExecutionState

RWExecutionState values describe the execution states of a runnable object. These values are returned by the getExecutionState() member functions of all runnable handles. A newly constructed runnable starts in RW_THR_INITIAL. After the application calls RWRunnable::start() on the runnable handle, but before the target executable code is executed, the runnable is in RW_THR_STARTING. While the runnable is executing its executable code, the runnable is in RW_THR_RUNNING. After the runnable finishes, it returns to RW_THR_INITIAL.

The other RWExecutionState values correspond to operations made through the runnable's handle. A runnable enters the RW_THR_YIELDING or RW_THR_SLEEPING states only if the runnable handle's methods are called to yield or sleep. The global functions rwYield() or rwSleep() do not change the state of the runnable.

Enumerator
RW_THR_INITIAL	Constructed; waiting for start or restart
RW_THR_STARTING	Runnable started, but has not started executing yet
RW_THR_RUNNING	Active, executing
RW_THR_INTERRUPTED	Active; Waiting for RWRunnable::releaseInterrupt()
RW_THR_SUSPENDED	Active; Waiting for RWThread::resume()
RW_THR_SLEEPING	Active; Waiting for expiration of sleep period
RW_THR_YIELDING	Active; Yielded execution to other runnables, waiting for execution
RW_THR_CANCELING	Active; Runnable cancellation in progress (CANCELING replaces RUNNING)
RW_THR_ABORTING	Active; Aborting cancellation (ABORTING replaces CANCELING)
RW_THR_TERMINATING	Active; Terminating an RWThread runnable
RW_THR_EXCEPTION	Active; Exiting with an exception
RW_THR_SERVER_WAIT	Active; Server waiting for another runnable to execute

enum RWInheritancePolicy

RWInheritancePolicy values indicate whether default settings are provided by the creating thread or the thread attribute.

See also

RWThreadAttribute

Enumerator
RW_THR_INHERIT	The default scheduling policy, priority, and time-slice quantum are inherited from the creating thread.
RW_THR_EXPLICIT	The default scheduling policy, priority, and time-slice quantum are provided by the thread attribute instance.

enum RWSchedulingPolicy

RWSchedulingPolicy values determine the scheduling policy.

See also

RWThreadAttribute

Enumerator
RW_THR_OTHER	A scheduling policy other than those listed below.
RW_THR_TIME_SLICED	Time-sliced with unspecified adjustments.
RW_THR_TIME_SLICED_FIXED	Time-sliced with fixed priorities.
RW_THR_TIME_SLICED_DYNAMIC	Time-sliced with dynamic priorities and/or time-slice quantums.
RW_THR_PREEMPTIVE	No time slicing and fixed priorities.

enum RWStartPolicy

Determines whether a thread is in an interrupted state or is ready to run after the RWThread::start() operation is complete.

See also

RWThreadAttribute

Enumerator
RW_THR_START_RUNNING	A newly created thread may run as soon as the RWThread::start() operation is complete.
RW_THR_START_INTERRUPTED	A newly created thread is left in an interrupted state upon return from the RWThread::start() invocation that created it. The thread must be explicitly released from the interrupt before it will execute the RWRunnable::run() method.