RWRunnableSelf Class Reference

Handle class for a runnable object. More...

#include <rw/thread/RWRunnableSelf.h>

Inheritance diagram for RWRunnableSelf:

Public Member Functions
	RWRunnableSelf ()
	RWRunnableSelf (const RWRunnableSelf &second)
	RWRunnableSelf (RWStaticCtor)
	~RWRunnableSelf ()
RWRunnableSelf	getNestedRunnable () const
RWRunnable	getRWRunnable () const
void	interrupt ()
RWRunnableSelf &	operator= (const RWRunnableSelf &second)
void	serviceCancellation ()
bool	serviceInterrupt ()
void	sleep (unsigned long milliseconds)
void	yield ()
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

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

Friends
class	RWRunnable

Related Symbols
(Note that these are not member symbols.)
RWRunnableSelf	rwRunnable ()
void	rwSleep (unsigned long milliseconds)
void	rwYield ()

Detailed Description

The RWRunnableSelf 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 RWRunnableSelf class provides an interface for the thread executing inside of a runnable. It defines the runnable member functions that may only be executed by the internal thread. Threads executing outside of a runnable should access the runnable using the RWRunnable handle class. The RWRunnableHandle class defines those functions that may be accessed from either inside or outside of a runnable.

To retrieve an RWRunnableSelf handle instance for the current runnable, use the rwRunnable() function. You may also convert an RWRunnable handle to an RWRunnableSelf handle by calling the member RWRunnable::getRWRunnableSelf(), but any attempt to violate the thread access restrictions imposed by the separate interfaces will generally result in an RWTHRIllegalAccess exception.

See also

RWRunnable, RWRunnableFunction, RWTRunnableIOUFunction, RWRunnableServer, RWServerPool, RWThread, RWThreadFunction, RWTThreadIOUFunction

Constructor & Destructor Documentation

RWRunnableSelf() [1/4]

RWRunnableSelf::RWRunnableSelf ( )

inline

Constructs an empty (invalid) handle instance.

RWRunnableSelf() [2/4]

RWRunnableSelf::RWRunnableSelf ( RWStaticCtor )

inline

Constructs a global static handle instance (may be assigned before it is constructed).

RWRunnableSelf() [3/4]

RWRunnableSelf::RWRunnableSelf ( const RWRunnableSelf & second )

inline

Copy constructor.

~RWRunnableSelf()

RWRunnableSelf::~RWRunnableSelf ( )

inline

Destructor.

RWRunnableSelf() [4/4]

RWRunnableSelf::RWRunnableSelf ( const RWRunnable & second )

protected

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

Member Function Documentation

getNestedRunnable()

RWRunnableSelf RWRunnableSelf::getNestedRunnable

(

)

const

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

getRWRunnable()

RWRunnable RWRunnableSelf::getRWRunnable

(

)

const

Returns an external interface handle bound to the same runnable instance (if any) pointed to by this handle.

interrupt()

void RWRunnableSelf::interrupt

(

)

Interrupts the calling thread executing within the runnable until the runnable is released by another thread. Changes execution state to RW_THR_INTERRUPTED. Possible exceptions include RWTHRInvalidPointer, RWTHRInternalError, and RWTHRIllegalAccess.

operator=()

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

inline

Assignment operator.

serviceCancellation()

void RWRunnableSelf::serviceCancellation

(

)

Checks for cancellation requests, throwing an RWCancellation object if cancellation has been requested, and returning otherwise. May result in a change of execution state to RW_THR_CANCELING. Other possible exceptions include RWTHRInvalidPointer, RWTHRInternalError, and RWTHRIllegalAccess.

serviceInterrupt()

bool RWRunnableSelf::serviceInterrupt

(

)

Checks for interrupt requests, blocking the calling thread if an interrupt has been requested and returning immediately if no interrupt requests are pending. May result in a change of execution state to RW_THR_INTERRUPTED. This function may only be called by an internal thread. Possible exceptions include RWTHRInvalidPointer, RWTHRInternalError, and RWTHRIllegalAccess.

sleep()

void RWRunnableSelf::sleep

(

unsigned long

milliseconds

)

Causes the calling thread, executing within the runnable, to sleep for the specified time period yielding execution to other threads. Temporarily changes the execution state to RW_THR_SLEEPING while sleeping, then restores the previous execution state. The global function rwSleep() may be used instead of this function, but rwSleep() does not produce any execution state changes in a runnable instance while this member does. Possible exceptions include RWTHRInvalidPointer, RWTHRInternalError, and RWTHRIllegalAccess.

yield()

void RWRunnableSelf::yield

(

)

Causes the calling thread, executing within the runnable, to yield execution to other threads. Temporarily changes the execution state to RW_THR_YIELDING, and then restores the previous execution state. The global function rwYield() may be used instead of this function, but rwYield() does not produce any execution state changes in a runnable instance while this member does. Possible exceptions include RWTHRInvalidPointer, RWTHRInternalError, and RWTHRIllegalAccess.

Friends And Related Symbol Documentation

rwRunnable()

RWRunnableSelf rwRunnable ( )

related

Retrieves an RWRunnableSelf handle for the current runnable object associated with the calling thread. If the calling thread was created by some means other than those provided by the Threads Module, then this function will return an empty runnable handle. If the thread was created by a Threads Module runnable class, then the runnable returned will be the current, inner-most nested runnable. If the code calling this function cannot be sure of the source of the calling thread, then it should test the validity of the returned handle, before using it, by testing the result of a call to the isValid() member of the handle.

See also

RWRunnableSelf, RWRunnableHandle::isValid()

rwSleep()

void rwSleep ( unsigned long milliseconds )

related

Use this function to put the calling thread to sleep for the specified number of milliseconds (thousandths of a second). Calling this function from within a thread created using the Threads Module will not change the execution state of any runnable associated with that thread. To cause the thread to register a runnable state change for the sleep operation, use the RWRunnableSelf::sleep() member function of the current runnable.

See also

RWRunnableSelf::sleep()

rwYield()

void rwYield ( )

related

This function causes the calling thread to yield execution to another thread waiting to be scheduled. The calling thread will be placed back on the queue of runnable threads until the scheduler decides to run it again. Calling this function from within a thread created using the Threads Module will not change the execution state of any runnable associated with that thread. To cause the Threads Module thread to register a runnable state change for the yield operation, use the RWRunnableSelf::yield() member function of the runnable handle.