RWThread Class Reference

Handle class for a threaded runnable object. More...

#include <rw/thread/RWThread.h>

Inheritance diagram for RWThread:

Public Member Functions
	RWThread ()
	RWThread (RWStaticCtor)
	RWThread (const RWThread &second)
	~RWThread ()
bool	canGetPriority () const
bool	canGetProcessScopePriority () const
bool	canGetSchedulingPolicy () const
bool	canGetSystemScopePriority () const
bool	canGetTimeSliceQuantum () const
bool	canSetPriority () const
bool	canSetProcessScopePriority () const
bool	canSetSchedulingPolicy (RWSchedulingPolicy policy) const
bool	canSetSystemScopePriority () const
bool	canSetTimeSliceQuantum () const
RWThreadAttribute	getActiveAttribute () const
RWThreadAttribute	getAttribute () const
RWPriority	getMaxPriority () const
RWPriority	getMaxProcessScopePriority () const
RWPriority	getMaxSystemScopePriority () const
unsigned long	getMaxTimeSliceQuantum () const
RWPriority	getMinPriority () const
RWPriority	getMinProcessScopePriority () const
RWPriority	getMinSystemScopePriority () const
unsigned long	getMinTimeSliceQuantum () const
RWPriority	getPriority () const
RWPriority	getProcessScopePriority () const
RWThreadSelf	getRWThreadSelf () const
RWSchedulingPolicy	getSchedulingPolicy () const
unsigned	getSuspendCount () const
RWPriority	getSystemScopePriority () const
unsigned long	getTimeSliceQuantum () const
RWThread &	operator= (const RWThread &second)
unsigned	resume ()
void	setAttribute (const RWThreadAttribute &second)
void	setPriority (RWPriority priority)
void	setProcessScopePriority (RWPriority priority)
void	setSchedulingPolicy (RWSchedulingPolicy policy)
void	setSystemScopePriority (RWPriority priority)
void	setTimeSliceQuantum (unsigned long milliseconds)
unsigned	suspend ()
void	terminate ()
Public Member Functions inherited from RWRunnable
	RWRunnable ()
	RWRunnable (RWStaticCtor)
	RWRunnable (const RWRunnable &second)
	~RWRunnable ()
RWRunnable	getNestedRunnable () const
RWRunnableSelf	getRWRunnableSelf () const
void	join (void)
RWWaitStatus	join (unsigned long milliseconds)
RWRunnable &	operator= (const RWRunnable &second)
void	raise () const
void	releaseInterrupt ()
RWWaitStatus	requestCancellation ()
RWWaitStatus	requestCancellation (unsigned long milliseconds)
RWWaitStatus	requestInterrupt ()
RWWaitStatus	requestInterrupt (unsigned long milliseconds)
RWCompletionState	start ()
RWExecutionState	wait (unsigned long stateMask)
RWWaitStatus	wait (unsigned long stateMask, RWExecutionState *state, unsigned long milliseconds)
Public Member Functions inherited from RWRunnableHandle
void	addCallback (const RWTFunctor< void(const RWRunnable &, RWExecutionState)> &functor, unsigned long stateMask, RWCallbackScope scope=RW_CALL_REPEATEDLY)
RWCompletionState	getCompletionState () const
RWExecutionState	getExecutionState () const
bool	isInterruptRequested () const
bool	isSelf () const
bool	isSelf (const RWThreadId &id) const
void	removeCallback (const RWTFunctor< void(const RWRunnable &, RWExecutionState)> &functor)
RWThreadId	threadId () const
Public Member Functions inherited from RWHandleBase
bool	isValid (void) const
bool	operator!= (const RWHandleBase &second) const
bool	operator< (const RWHandleBase &second) const
bool	operator== (const RWHandleBase &second) const

Static Public Member Functions
static bool	canGetMaxThreads ()
static bool	canSuspendResume ()
static size_t	getMaxThreads ()

Protected Member Functions
	RWThread (RWThreadImp *threadImpP)
Protected Member Functions inherited from RWRunnable
	RWRunnable (const RWRunnableSelf &second)
Protected Member Functions inherited from RWRunnableHandle
	RWRunnableHandle ()
	RWRunnableHandle (RWStaticCtor)
	RWRunnableHandle (RWRunnableImp *runnableImpP)
	RWRunnableHandle (const RWRunnableHandle &second)
	~RWRunnableHandle ()
RWRunnableHandle &	operator= (const RWRunnableHandle &second)
Protected Member Functions inherited from RWHandleBase
	RWHandleBase (void)
	RWHandleBase (RWStaticCtor)
	RWHandleBase (RWBodyBase *body)
	RWHandleBase (const RWHandleBase &second)
	~RWHandleBase (void)
RWBodyBase &	body (void) const
RWHandleBase &	operator= (const RWHandleBase &second)

Detailed Description

The RWThread class is a handle class for a threaded runnable object, providing an interface for threads that execute outside the threaded runnable.

A threaded runnable object provides the basic mechanisms used to create, control, and monitor the threads of execution within your application. Threaded runnables create their own thread to perform some task or activity.

Each threaded runnable object is reference-counted; a threaded runnable body instance keeps a count of the number of handles that currently reference it. A runnable object is deleted when the last handle that references the body is deleted.

A threaded runnable handle class instance may be empty. Any attempt to use an empty handle to access a threaded runnable produces an RWTHRInvalidPointer exception.

The public interface for a threaded runnable is provided by its handle classes. Many of the public functions in a handle simply forward control to a corresponding protected function in the body class.

The RWThread class provides an interface for threads executing outside of a threaded runnable, defining member functions that may be executed only by an external thread. The threads executing inside of a threaded runnable should access the runnable using the RWThreadSelf handle class. Functions available from either inside or outside of a threaded runnable are defined in both handle classes.

You may also convert an RWThreadSelf handle to an RWThread handle by calling the RWThreadSelf::getRWThread() member, but any attempt to violate the thread access restrictions imposed by the separate interfaces results in an RWTHRIllegalAccess exception.

See also

RWThreadSelf, RWRunnable, RWRunnableHandle, RWThreadFunction, RWTThreadIOUFunction, RWRunnableServer, RWServerPool, RWThreadAttribute

Constructor & Destructor Documentation

RWThread::RWThread ( )

inline

Creates an empty RWThread handle. Until this object is bound to a threaded runnable, its isValid() member returns false.

RWThread::RWThread ( RWStaticCtor  )

inline

Constructor that creates a global static RWThread handle object that may be assigned to before construction. This constructor does not change the static instance.

RWThread::RWThread ( const RWThread &  second )

inline

Copy constructor. Creates an RWThread object and binds it to the same threaded runnable, if any, pointed to by second.

RWThread::~RWThread ( )

inline

Destructor.

RWThread::RWThread ( RWThreadImp *  threadImpP )

protected

Associates a new thread with self.

Member Function Documentation

static bool RWThread::canGetMaxThreads ( )

static

Returns true if the getMaxThreads() function is supported in the current environment, otherwise false.

bool RWThread::canGetPriority

(

)

const

Returns true if the priority attribute is supported in the current environment and if the getPriority() function can return a legal value under the current circumstances. For example, returns true only if RW_THR_HAS_PRIORITY is defined and calling functions such as getPriority() and getMaxPriority() can return a legal value under the current circumstances.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

bool RWThread::canGetProcessScopePriority

(

)

const

Returns true if the process-scope priority attribute is supported in the current environment and if the getProcessScopePriority() function can return a legal value under the current circumstances.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

bool RWThread::canGetSchedulingPolicy

(

)

const

Returns true if the scheduling policy attribute is supported in the current environment and if the getSchedulingPolicy() function can return a legal value under the current circumstances.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

bool RWThread::canGetSystemScopePriority

(

)

const

Returns true if the system-scope priority attribute is supported in the current environment and if the getSystemScopePriority() function can return a legal value under the current circumstances.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

bool RWThread::canGetTimeSliceQuantum

(

)

const

Returns true if the time-slice quantum attribute is supported in the current environment and if the getTimeSliceQuantum() function can return a legal value under the current circumstances.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

bool RWThread::canSetPriority

(

)

const

Returns true if the priority attribute is supported in the current environment and if the function setPriority() is callable under the current circumstances. For example, returns true only if RW_THR_HAS_PRIORITY is defined and calling setPriority() is supported under the current options. In addition, the function returns true only if both the calling thread and process have sufficient privileges to perform the requested operation.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

bool RWThread::canSetProcessScopePriority

(

)

const

Returns true if the process-scope priority attribute is supported in the current environment and if the function setProcessScopePriority() is callable under the current circumstances. For example, returns true only if RW_THR_HAS_PROCESS_SCOPE_PRIORITY is defined and calling setProcessScopePriority() is supported under the current options. In addition, the function returns true only if both the calling thread and process have sufficient privileges to perform the requested operation.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

bool RWThread::canSetSchedulingPolicy

(

RWSchedulingPolicy

policy

)

const

Returns true if the scheduling-policy attribute is supported in the current environment and if the function setSchedulingPolicy() is callable under the current circumstances. For example, returns true only if RW_THR_HAS_SCHEDULING_POLICY is defined and calling setSchedulingPolicy() is supported under the current options. In addition, the function returns true only if both the calling thread and process have sufficient privileges to perform the requested operation.

Possible exceptions include RWTHRInvalidPointer, RWTHRInternalError, and RWTHRBoundsError.

bool RWThread::canSetSystemScopePriority

(

)

const

Returns true if the system-scope priority attribute is supported in the current environment and if the function setSystemScopePriority() is callable under the current circumstances. For example, returns true only if RW_THR_HAS_SYSTEM_SCOPE_PRIORITY is defined and calling setSystemScopePriority() is supported under the current options. In addition, the function returns true only if both the calling thread and process have sufficient privileges to perform the requested operation.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

bool RWThread::canSetTimeSliceQuantum

(

)

const

Returns true if the time-slice quantum attribute is supported in the current environment and if the function setTimeSliceQuantum() is callable under the current circumstances. For example, returns true only if RW_THR_HAS_TIME_SLICE_QUANTUM is defined and calling setTimeSliceQuantum() is supported under the current options. In addition, the function returns true only if both the calling thread and process have sufficient privileges to perform the requested operation.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

static bool RWThread::canSuspendResume ( )

static

Returns true if the current environment supports the suspend() and resume() members functions, otherwise false.

RWThreadAttribute RWThread::getActiveAttribute

(

)

const

Returns a handle to the thread attribute instance used to initialize the most recently created thread. If a thread has not yet been created, returns a copy of a default thread attribute instance.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

RWThreadAttribute RWThread::getAttribute

(

)

const

Returns a handle to the thread attribute instance used to initialize any threads created by future calls to start(). Use getActiveAttribute() to get a copy of the attribute instance actually used to initialize the most recently started thread.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

RWPriority RWThread::getMaxPriority

(

)

const

Returns the maximum priority value that may be specified for this thread. At runtime, use canGetPriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError.

RWPriority RWThread::getMaxProcessScopePriority

(

)

const

Returns the maximum process-scope priority value that may be specified for this thread. At runtime, use canGetProcessScopePriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_PROCESS_SCOPE_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError.

RWPriority RWThread::getMaxSystemScopePriority

(

)

const

Returns the maximum system-scope priority value that may be specified for this thread. At runtime, use canGetSystemScopePriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_SYSTEM_SCOPE_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError.

static size_t RWThread::getMaxThreads ( )

static

Returns the maximum number of threads that may be created in this environment. This function is not supported in all environments. At runtime, use canGetMaxThreads() to determine whether this feature is available. At compile time, check to see if RW_THR_HAS_MAX_THREADS is defined.

Possible exceptions include RWTHROperationNotSupported.

unsigned long RWThread::getMaxTimeSliceQuantum

(

)

const

Returns the maximum time-slice quantum value that may be specified for this thread. At runtime, use canGetTimeSliceQuantum() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_TIME_SLICE_QUANTUM is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError.

RWPriority RWThread::getMinPriority

(

)

const

Returns the minimum priority value that may be specified for this thread. At runtime, use canGetPriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError.

RWPriority RWThread::getMinProcessScopePriority

(

)

const

Returns the minimum process-scope priority value that may be specified for this thread. At runtime, use canGetProcessScopePriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_PROCESS_SCOPE_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError.

RWPriority RWThread::getMinSystemScopePriority

(

)

const

Returns the minimum system-scope priority value that may be specified for this thread. At runtime, use canGetSystemScopePriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_SYSTEM_SCOPE_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError. and RWTHRInternalError.

unsigned long RWThread::getMinTimeSliceQuantum

(

)

const

Returns the minimum time-slice quantum value that may be specified for this thread. At runtime, use canGetTimeSliceQuantum() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_TIME_SLICE_QUANTUM is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError.

RWPriority RWThread::getPriority

(

)

const

Returns the current priority for the active thread associated with self. At runtime, use canGetPriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHRThreadNotActive, and RWTHRInternalError.

RWPriority RWThread::getProcessScopePriority

(

)

const

Returns the current process-scope priority for the active thread associated with self. At runtime, use canGetProcessScopePriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_PROCESS_SCOPE_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError.

RWThreadSelf RWThread::getRWThreadSelf

(

)

const

Returns an internal thread interface associated with the thread, if any, associated with self.

RWSchedulingPolicy RWThread::getSchedulingPolicy

(

)

const

Returns the current scheduling policy for the active thread associated with self. At runtime, use canGetSchedulingPolicy() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_SCHEDULING_POLICY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHRThreadNotActive, and RWTHRInternalError.

unsigned RWThread::getSuspendCount

(

)

const

Returns the number of times this thread has been suspended without being released. A return value of zero indicates that the thread is not currently suspended.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, and RWTHRInternalError.

RWPriority RWThread::getSystemScopePriority

(

)

const

Returns the current system-scope priority for the active thread associated with self. At runtime, use canGetSystemScopePriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_SYSTEM_SCOPE_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError.

unsigned long RWThread::getTimeSliceQuantum

(

)

const

Returns the current time-slice quantum value for the active thread associated with self. At runtime, use canGetTimeSliceQuantum() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_TIME_SLICE_QUANTUM is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, and RWTHRInternalError.

RWThread & RWThread::operator= ( const RWThread &  second )

inline

Assignment operator. Binds the handle to the same threaded runnable, if any, pointed to by second.

unsigned RWThread::resume

(

)

Resumes this thread after it has been suspended. At runtime, use canSuspendResume() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_SUSPEND_RESUME is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHRIllegalAccess, RWTHRThreadNotActive, and RWTHRInternalError.

void RWThread::setAttribute

(

const RWThreadAttribute &

second

)

Replaces the thread attribute instance used to initialize any threads created by future calls to start(). Changing a thread's attribute instance after the thread has been started does not affect its current thread.

Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

void RWThread::setPriority

(

RWPriority

priority

)

Changes the priority of thread associated with self. At runtime, use canSetPriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, RWTHRBoundsError, RWTHRResourceLimit, and RWTHRInternalError.

void RWThread::setProcessScopePriority

(

RWPriority

priority

)

Changes the process-scope priority of the thread associated with self. At runtime, use canSetProcessScopePriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_PROCESS_SCOPE_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, RWTHRBoundsError, RWTHRResourceLimit, and RWTHRInternalError.

void RWThread::setSchedulingPolicy

(

RWSchedulingPolicy

policy

)

Changes the scheduling policy of the thread associated with self. At runtime, use canSetSchedulingPolicy%(policy) to determine the availability of this feature. At compile time check to see if RW_THR_HAS_SCHEDULING_POLICY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, RWTHRBoundsError, RWTHRResourceLimit, and RWTHRInternalError.

void RWThread::setSystemScopePriority

(

RWPriority

priority

)

Changes the system-scope priority of the thread associated with self. At runtime, use canSetSystemScopePriority() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_SYSTEM_SCOPE_PRIORITY is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, RWTHRBoundsError, RWTHRResourceLimit, and RWTHRInternalError.

void RWThread::setTimeSliceQuantum

(

unsigned long

milliseconds

)

Changes the time-slice quantum value of the thread associated with self. At runtime, use canSetTimeSliceQuantum() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_TIME_SLICE_QUANTUM is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHROperationNotAvailable, RWTHRThreadNotActive, RWTHRBoundsError, RWTHRResourceLimit, and RWTHRInternalError.

unsigned RWThread::suspend

(

)

Suspends the execution of the thread associated with self until a matching resume() operation is performed.

Warning

Use of this function may produce unexpected deadlock (see the Threads User's Guide for more information). For deadlock-safe suspension, use requestInterrupt() and serviceInterrupt() instead.

At runtime, use canSuspendResume() to determine the availability of this feature. At compile time, check to see if RW_THR_HAS_SUSPEND_RESUME is defined.

Possible exceptions include RWTHRInvalidPointer, RWTHROperationNotSupported, RWTHRThreadNotActive, and RWTHRInternalError.

void RWThread::terminate

(

)

Deprecated:

As of SourcePro 13. Explicit thread termination should be avoided.

Terminates execution of this thread.

Warning

This operation kills the associated thread without giving it a chance to release locks, unwind the stack, or recover resources. Use only as a last resort.

Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, RWTHRThreadNotActive, RWTHRThreadActive, and RWTHRInternalError.