RWRunnable Class Reference

Handle class for a runnable object, i.e. one that controls an application's threads of execution. More...

#include <rw/thread/RWRunnable.h>

Inheritance diagram for RWRunnable:

Public Member Functions
	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

Protected Member Functions
	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 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 produces an RWTHRInvalidPointer exception.

The RWRunnable class provides an interface for threads executing outside a runnable. It defines the runnable member functions that may be executed only 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::getRWRunnable() 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, 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.

Constructor & Destructor Documentation

RWRunnable::RWRunnable ( )

inline

Constructs an empty (invalid) handle.

RWRunnable::RWRunnable ( RWStaticCtor  )

inline

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

RWRunnable::RWRunnable ( const RWRunnable &  second )

inline

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

RWRunnable::~RWRunnable ( )

inline

Destructor.

RWRunnable::RWRunnable ( const RWRunnableSelf &  second )

inlineprotected

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

Member Function Documentation

RWRunnable RWRunnable::getNestedRunnable

(

)

const

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

RWRunnableSelf RWRunnable::getRWRunnableSelf

(

)

const

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

void RWRunnable::join

(

void

)

Waits for this runnable to complete execution. Returns immediately if the runnable has already been started, has completed, and is currently inactive. Waits for the runnable to start and then complete if it has not 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; application code will need to synchronize the threads starting the runnable with the threads joining the runnable so that joining threads know which iteration they are joining. Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

RWWaitStatus RWRunnable::join

(

unsigned long

milliseconds

)

Waits for this runnable to complete execution or until expiration of the specified timeout period provided by milliseconds. Returns immediately if the runnable has already been started, has completed, and is currently inactive. Waits for the runnable to start and then complete if it has not 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.

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

inline

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

void RWRunnable::raise

(

)

const

Throws 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 RWRunnable::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 RWRunnable::requestCancellation

(

)

Requests and waits for the runnable to cancel itself.

This function returns RW_THR_COMPLETED to indicate that the runnable was canceled, exited, or was not active; or 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 stays marked as canceled until the next time start() is called.

RWWaitStatus RWRunnable::requestCancellation

(

unsigned long

milliseconds

)

Requests and waits for the runnable to cancel itself or until the specified milliseconds has passed. This function returns RW_THR_COMPLETED to indicate that the runnable was canceled, exited, or was not active; 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 stays marked as canceled until the next time start() is called.

Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

RWWaitStatus RWRunnable::requestInterrupt

(

)

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 RWRunnableSelf::serviceInterrupt(). The interrupted thread is blocked inside the RWRunnableSelf::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, and 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 changes to RW_THR_INTERRUPTED until the interrupt is released.

Possible exceptions include RWTHRInvalidPointer, RWTHRIllegalAccess, and RWTHRInternalError.

RWWaitStatus RWRunnable::requestInterrupt

(

unsigned long

milliseconds

)

This function is the same as requestInterrupt(), but allows the application to limit the time the calling thread will wait by specifying 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 RWRunnable::start

(

)

Starts execution of the runnable object. For synchronous implementations (for example, RWRunnableFunction) the associated code executes synchronously within the runnable object, and this function waits for the associated code to complete before returning. For asynchronous implementations (for example, RWThreadFunction) the associated code runs asynchronously within the runnable, and this function returns immediately.

Calling start() changes the execution state to RW_THR_STARTING, and then for synchronous runnables, changes it next 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 RWRunnable::wait

(

unsigned long

stateMask

)

Waits until the runnable object enters an execution state referenced by the mask stateMask. The mask is a union of states that causes 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 RWRunnable::wait	(	unsigned long	stateMask,
		RWExecutionState *	state,
		unsigned long	milliseconds
	)

Waits until the runnable object enters a state contained in the mask stateMask, or until the time-out period of milliseconds has elapsed. The mask is a union of states that causes wait() to unblock and return. If a masked state is entered prior to the expiration of the time-out period, this function writes 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.