RWThread

Module:  Threads   Package:  Threading

RWThread   RWRunnable

• Local Index
• Header File
• Description
• Static Member Functions
• Public Constructors
• Public Destructor
• Public Member Operator
• Public Member Functions
• Protected Constructors
• See Also

Members

canGetMaxThreads() canGetPriority() canGetProcessScopePriority() canGetSchedulingPolicy() canGetSystemScopePriority() canGetTimeSliceQuantum() canSetPriority() canSetProcessScopePriority() canSetSchedulingPolicy() canSetSystemScopePriority() canSetTimeSliceQuantum()

canSuspendResume() getActiveAttribute() getAttribute() getMaxPriority() getMaxProcessScopePriority() getMaxSystemScopePriority() getMaxThreads() getMaxTimeSliceQuantum() getMinPriority() getMinProcessScopePriority() getMinSystemScopePriority()

getMinTimeSliceQuantum() getPriority() getProcessScopePriority() getRWThreadSelf() getSchedulingPolicy() getSuspendCount() getSystemScopePriority() getTimeSliceQuantum() operator=() resume() RWThread()

setAttribute() setPriority() setProcessScopePriority() setSchedulingPolicy() setSystemScopePriority() setTimeSliceQuantum() suspend() terminate() ~RWThread()

#include <rw/thread/RWThread.h>

The RWThread class is a handle class for a threaded runnable object.

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.

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. A threaded runnable handle class instance may be empty. Any attempt to use an empty handle to access a threaded runnable will produce an RWTHRInvalidPointer exception

The RWThread class provides an interface for threads executing outside of a threaded runnable. It defines the member functions that may only be executed by an external thread. The threads executing inside of a threaded runnable should access the runnable using the RWThreadSelf handle class. Those functions that can be accessed 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::getThread() member, but any attempt to violate the thread access restrictions imposed by the separate interfaces will generally result in an RWTHRIllegalAccess exception.

bool
canGetMaxThreads();

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

bool
canSuspendResume();

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

size_t
getMaxThreads();

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.

RWThread();

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

RWThread(RWStaticCtor);

This constructor allows you to create a global static RWThread handle object that may be assigned to before it is constructed. This constructor does not change the static instance.

RWThread(const RWThread& second);

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

~RWThread();

Destructor.

RWThread&
operator=(const RWThread& second)

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

bool
canGetPriority() const;
bool
canGetProcessScopePriority() const;
bool
canGetSchedulingPolicy() const;
bool
canGetSystemScopePriority() const;
bool
canGetTimeSliceQuantum() const;

Each of these functions returns true if the corresponding attribute is supported in the current environment and if the corresponding "get" functions can return a legal value under the current circumstances. For example, canGetPriority() will return 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
canSetPriority() const;
bool
canSetProcessScopePriority() const;
bool
canSetSchedulingPolicy(RWSchedulingPolicy policy) const;
bool
canSetSystemScopePriority() const;
bool
canSetTimeSliceQuantum() const;

Each of these functions returns true if the corresponding attribute is supported in the current environment and if the corresponding "set" function is callable under the current circumstances. For example, canSetPriority() will return true only if RW_THR_HAS_PRIORITY is defined and calling setPriority() is supported under the current options. In addition, the function will only return true if both the calling thread and process have sufficient privileges to perform the requested operation.

All of these functions can throw exceptions RWTHRInvalidPointer and RWTHRInternalError. In addition, canSetSchedulingPolicy() can throw RWTHRBoundsError.

RWThreadAttribute
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, this function will simply return a copy of a default thread attribute instance. Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

RWThreadAttribute
getAttribute() const;

Returns a handle to the thread attribute object that will be 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
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
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
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.

unsigned long
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
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
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
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.

unsigned long
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
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
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
getRWThreadSelf() const;

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

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

unsigned
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
setAttribute(const RWThreadAttribute& second);

Replaces the thread attribute instance that will be used to initialize any threads created by future calls to start(). Changing a thread's attribute object after the thread has been started will not affect its current thread. Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

void
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
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
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
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
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, and RWTHRInternalError.

unsigned
suspend();

Suspends the execution of the thread associated with self until a matching resume() operation is performed. Caution: Use of this function may produce unexpected deadlock (see the 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
terminate();

Terminates execution of this thread. Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, RWTHRThreadNotActive, RWTHRThreadActive, and RWTHRInternalError.

---

NOTE -- 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!

---

RWThread(RWThreadImp* threadImpP);

Associates a new thread with self.

RWThreadSelf, RWRunnable, RWRunnableHandle, RWThreadFunction, RWTThreadIOUFunction<Return>, RWRunnableServer, RWServerPool, RWThreadAttribute

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.