RWRunnable

Module:  Threads   Package:  Threading

RWRunnable   RWRunnableHandle

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

Members

getNestedRunnable() getRWRunnableSelf() join()

operator=() raise() releaseInterrupt()

requestCancellation() requestInterrupt() RWRunnable()

start() wait() ~RWRunnable()

#include <rw/thread/RWRunnable.h> 

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.

RWRunnable();

Constructs an empty (invalid) handle.

RWRunnable(RWStaticCtor);

Constructs a global static handle instance which may be assigned to before construction. The static constructor will not change the instance state.

RWRunnable(const RWRunnable& second);

Binds a new handle to the runnable instance, if any, pointed to by the handle second.

~RWRunnable();

Destructor.

RWRunnable&
operator=(const RWRunnable& second);

Binds this to the runnable instance, if any, pointed to by the RWRunnable handle second.

RWRunnableSelf
getRWRunnableSelf() const;

Returns an internal interface bound to the same runnable instance, if any, pointed to by self.

RWRunnable
getNestedRunnable() const;

Returns a handle to the nested runnable object, if any. Possible exceptions include RWTHRInvalidPointer and RWTHRInternalError.

void
join();

Waits for this runnable to complete execution. Returns immediately if the runnable has already been started and has completed and is currently inactive. Waits for the runnable to start and then complete if it has never been started. If the runnable object is going to be restarted, this function should be used with care by threads other than the thread starting the runnable; user code will need to synchronize the threads starting the runnable with the threads joining the runnable so that joining threads will know which iteration they are joining. Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

RWWaitStatus
join(unsigned long milliseconds);

Waits for this runnable to complete execution or until expiration of the specified timeout period. Returns immediately if the runnable has already been started and completed and is currently inactive. Waits for the runnable to start and then complete if it has never been started. If the runnable object is going to be restarted, this function should be used with care by threads other than the thread starting the runnable, so that joining threads will know which start operation they are joining. Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

void
raise() const;

Throw the exception, if any, stored by the runnable during execution of the associated code. This function simply returns if no exception was produced during the most recently completed execution of this runnable.

void
releaseInterrupt();

Reactivates a thread executing within the runnable which had been interrupted via requestInterrupt(). This function restores the execution state of the runnable to the state it was in prior to being interrupted. Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, RWTHRThreadActive, and RWTHRInternalError.

RWWaitStatus
requestCancellation();

Requests and waits for the runnable to cancel itself. Cancellation starts when the thread running within the runnable instance calls serviceCancellation().

This function returns RW_THR_COMPLETED to indicate that the runnable was canceled, exited, or was not active anyway. It returns RW_THR_ABORTED to indicate that cancellation started but did not complete. Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

A cancellation request cannot be withdrawn; a runnable will stay marked as canceled until the next time start() is called.

RWWaitStatus
requestCancellation(unsigned long milliseconds);

Requests and waits for the runnable to cancel itself or until the specified amount of time has passed. This member returns RW_THR_COMPLETED to indicate that the runnable was canceled, exited, or was not active anyway; RW_THR_ABORTED to indicate that cancellation started but did not complete (the cancellation exception was caught and destroyed in a catch-block); or RW_THR_TIMEOUT to indicate that the time-out period elapsed before the runnable completed cancellation.

If the cancellation request times out, then the execution state may not have changed at all, or may have changed to RW_THR_CANCELING, in which case, cancellation has already started, and may yet abort or succeed. A cancellation request cannot be withdrawn; a runnable will stay marked as canceled until the next time start() is called.

Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

RWWaitStatus
requestInterrupt();

This function requests the thread executing within the runnable to interrupt and waits until that request is serviced. To respond to the request for an interrupt, the thread executing within the runnable must call serviceInterrupt(). The interrupted thread is blocked inside the serviceInterrupt() call until some other thread releases the interrupt by calling releaseInterrupt().

This function returns RW_THR_ABORTED if the runnable is not active when the call is made. It returns RW_THR_ACQUIRED if the runnable was successfully interrupted. A return value of RW_THR_ACQUIRED does not guarantee that the runnable will be in an interrupted state at the point of return. Since any thread may release a runnable from an interrupt, it is possible for a different thread to release the interrupt before this function returns. If the interrupt is serviced, the execution state will change to RW_THR_INTERRUPTED until the interrupt is released.

Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

RWWaitStatus
requestInterrupt(unsigned long milliseconds);

Same as the previous function except that the user limits the time the calling thread will wait by specifying a waiting interval of milliseconds. If the specified interval expires before the interrupt is serviced, this function returns RW_THR_TIMEOUT. Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

RWCompletionState
start();

Starts execution of the runnable object. For synchronous implementations (for example, RWRunnableFunction) the associated code will execute synchronously within the runnable object and this function will wait for the associated code to complete before returning. For asynchronous implementations (for example, RWThreadFunction) the associated code will run asynchronously within the runnable and this function will return immediately. Calling start() changes the execution state to RW_THR_STARTING, then for synchronous runnables, changes it to RW_THR_RUNNING. Asynchronous runnables enter the RW_THR_INTERRUPTED state shortly before starting, and are then automatically or manually released to RW_THR_RUNNING.

Possible exceptions include RWTHRInvalidPointer, RWTHRThreadActive, RWTHRResourceLimit, and RWTHRInternalError.

RWExecutionState
wait(unsigned long stateMask);

Waits until the runnable object enters an execution state referenced by the mask. The mask is a union of states which will cause wait() to unblock and return. The value returned is the execution state value that satisfied the specified mask. Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

RWWaitStatus 
wait(unsigned long stateMask, RWExecutionState* state, unsigned long milliseconds);

Waits until the runnable object enters a state contained in the mask, or until the time-out period of milliseconds has elapsed. The mask is a union of states which will cause wait() to unblock and return. If a masked state is entered prior to the expiration of the time-out period, this member will write the state value that satisfied the wait in the state argument location (if not rwnil), and returns a value of RW_THR_SIGNALED. If the time-out period elapses without a state change that satisfies the mask, then the function returns RW_THR_TIMEOUT without changing the storage specified by the state argument.

Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

RWRunnable(const RWRunnableSelf& second);

RWRunnableSelf conversion constructor. Constructs a new RWRunnable handle pointed to by second.

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

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