Rogue Wave banner
Previous fileTop of DocumentContentsIndexNext file

RWRunnable


RWRunnable RWRunnableHandle

Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Member Functions

Package

Threading

Header File

#include <rw/thread/RWRunnable.h> 

Description

The RWRunnable class is a handle class for a runnable object.

A runnable object provides the basic mechanisms used to create, control, and monitor the threads of execution within your application. Runnables are used to define the task or activity to be performed by a thread.

Each runnable object is reference-counted; a 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 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 runnable handle class instance may be empty. Any attempt to use an empty handle to access a runnable will produce an RWTHRInvalidPointer exception.

The RWRunnable class provides an interface for threads executing outside a runnable. It defines the runnable member functions that may only be executed by an external thread. The thread executing inside of a runnable should access the runnable using the RWRunnableSelf handle class. The RWRunnableHandle class defines those functions that may be accessed from either inside or outside of a runnable.

You may convert an RWRunnableSelf handle into an RWRunnable handle by calling the RWRunnableSelf::getRunnable() member, but any attempt to violate the thread access restrictions imposed by the separate interfaces will generally result in an RWTHRIllegalAccess exception.

The runnable object represented by an RWRunnable is executed by calling start(). A protected virtual run() member defines the work or activity to be performed by the runnable object. The start() member defines the form of dispatching to be used in executing the run() member, synchronous or asynchronous. Regardless of the dispatching mechanism, the run() member is always executed as a consequence of calling start().

In a synchronous runnable, the thread that calls start() is the same thread that executes run(); the flow of control is simply passed internally from the start() member to the run() member. By the time the start() function returns, the runnable will have completed, or at least attempted, to perform its specified task.

In an asynchronous, or threaded runnable, a call to start() results in the creation of a new thread of execution. Following creation, this new thread proceeds to execute the run() member, freeing the thread that called start() to move on to other things.

Only one thread can execute within a runnable at any time. Any attempt to call start() while a thread is executing within the runnable will result in an RWTHRThreadActive exception in the scope of the caller.

Once a runnable has been started, a any thread can wait for that runnable object to finish by calling the runnable's join() member.

If an exception occurs and is propagated out of a runnable's run() member, the runnable will catch the exception and store it. Clients of the RWRunnable class can rethrow this exception using the raise() member.

Clients of RWRunnable can request cancellation of an active runnable or interrupt the runnable's execution. RWRunnable also provides wait functions that allow another thread to block until the runnable enters an execution state of interest.

Public Constructors

RWRunnable(void);
RWRunnable(RWStaticCtor);
RWRunnable(const RWRunnable& second);

Public Member Operator

RWRunnable&
operator=(const RWRunnable& second);

Public Member Functions

RWRunnableSelf
getRWRunnableSelf(void) const;
RWRunnable
getNestedRunnable(void) const;
void
join(void);
RWWaitStatus
join(unsigned long milliseconds);
void
raise(void) const;
void
releaseInterrupt(void);
RWWaitStatus
requestCancellation(void);
RWWaitStatus
requestCancellation(unsigned long milliseconds);
RWWaitStatus
requestInterrupt(void);
RWWaitStatus
requestInterrupt(unsigned long milliseconds);
RWCompletionState
start(void);
RWExecutionState
wait(unsigned long stateMask);
RWWaitStatus 
wait(unsigned long stateMask, RWExecutionState* state, unsigned long milliseconds);

See Also

RWRunnableHandle, RWRunnableSelf, RWRunnableFunction, RWTRunnableIOUFunction<Return>, RWThread, RWThreadFunction, RWTThreadIOUFunction<Return>, RWRunnableServer, RWServerPool



Previous fileTop of DocumentContentsIndexNext file

©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.