RWTRunnableIOUFunction< Return > Class Template Reference

Handle class for functor-based runnable objects. More...

#include <rw/thread/RWTRunnableIOUFunction.h>

Inheritance diagram for RWTRunnableIOUFunction< Return >:

Public Member Functions
	RWTRunnableIOUFunction ()
	RWTRunnableIOUFunction (const RWTRunnableIOUFunction< Return > &second)
	~RWTRunnableIOUFunction ()
RWTFunctor< Return()>	getFunctor () const
RWTIOUResult< Return >	operator() () const
RWTRunnableIOUFunction< Return > &	operator= (const RWTRunnableIOUFunction< Return > &second)
RWTIOUResult< Return >	result () const
void	setFunctor (const RWTFunctor< Return()> &functor)
void	setIOUEscrow (const RWTIOUEscrow< Return > &escrow)
Public Member Functions inherited from RWRunnable
	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

Static Public Member Functions
static RWTRunnableIOUFunction< Return >	make ()
static RWTRunnableIOUFunction< Return >	make (const RWTFunctor< Return()> &functor)
static RWTRunnableIOUFunction< Return >	make (const RWTIOUEscrow< Return > &escrow, const RWTFunctor< Return()> &functor)

Additional Inherited Members
Protected Member Functions inherited from RWRunnable
	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

template<class Return>
class RWTRunnableIOUFunction< Return >

The RWTRunnableIOUFunction class is a handle class for functor-based runnable objects.

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.

A functor-based runnable accepts a functor object for execution. A functor is an object used to encapsulate a function call. Each functor keeps a pointer to the function and copies of the argument values that are to be passed to the function. Invoking a functor produces a call to the function, and in this case, a return value.

A functor-based runnable simply redefines the basic run() member to invoke a functor instance stored within the runnable. With this capability, you do not have to resort to sub-classing or other intrusive techniques to customize the execution behavior of a runnable. The functor-base runnables allow you to dynamically specify the functions you want to execute when a runnable is started.

RWTRunnableIOUFunction is used to access a synchronous runnable. A synchronous runnable executes the specified functor in the same thread that calls start(). The result of the functor is returned in the form of an IOU. An IOU may be obtained as soon as the runnable is created. To get the actual result from the IOU you must redeem it. If the result has not yet been calculated, the calling thread blocks until it has.

Although RWTRunnableIOUFunction is an RWRunnable, it does not store exceptions generated by its target function in the same way that other runnables do. Instead of setting the runnable state to RW_THR_EXCEPTION and storing the exception in the runnable, it intercepts the exception and sets it as an exception on the RWTIOUResult to be returned.

Since RWTRunnableIOUFunction does not store an RW_THR_EXCEPTION, a callback designed to detect it will not be triggered if the runnable function throws an exception. This differs from the usual runnable behavior. Another side effect is that, even if the runnable terminates because of an exception, calling raise() on the runnable does not generate the exception. Instead the IOUResult returned by the function throws the exception when it is redeemed.

Example

#include <iostream>
#include <math.h>
#include <rw/functor/rwBind.h>
#include <rw/thread/RWTRunnableIOUFunction.h>
#include <rw/thread/RWRunnableServer.h>

int greatestPrime(int limit)
{
    // The sieve of Eratosthenes:
    int i, m;
    char* sieve = new char[limit + 1];
    if (sieve == 0) {
        return -1;    // not enough memory
    }

    for (i = 0; i <= limit; ++i) {
        sieve[i] = 1;
    }
    for (i = 2; i <= sqrt((double)limit); ++i) {
        if (sieve[i] != 0) {
            for (m = i + i; m <= limit; m += i) {
                sieve[m] = 0;
            }
        }
    }

    // Return the greatest prime less than or equal to limit:
    for (i = limit; i >= 2; --i) {
        if (sieve[i] != 0) {
            return i;
        }
    }
    return 0;
}

int main()
{
    RWRunnableServer server = RWRunnableServer::make();

    RWTRunnableIOUFunction<int> eratosthenes
        = RWTRunnableIOUFunction<int>::make(rwBind(greatestPrime, 6000000));

    RWTIOUResult<int> answer
        = eratosthenes.result();  // get an IOU

    server.start();               // Start the server
    server.enqueue(eratosthenes); //calculate prime in server thread

    // While the thread is busy calculating, print this
    // suspenseful message to keep the user entertained:
    std::cout << "The greatest prime less than six million is... "
              << std::flush;

    // Block until the answer has been calculated and
    // then print it:
    std::cout << answer.redeem() << std::endl;

    server.stop();
    server.join();
    return 0;
}

OUTPUT:

The greatest prime less than six million is... 5999993

See also

RWTFunctor, RWRunnable, RWRunnableHandle

Constructor & Destructor Documentation

template<class Return >

RWTRunnableIOUFunction< Return >::RWTRunnableIOUFunction ( )

inline

Constructs an empty RWTRunnableIOUFunction handle instance.

template<class Return >

RWTRunnableIOUFunction< Return >::RWTRunnableIOUFunction ( const RWTRunnableIOUFunction< Return > &  second )

inline

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

template<class Return >

RWTRunnableIOUFunction< Return >::~RWTRunnableIOUFunction ( )

inline

Destructor.

Member Function Documentation

template<class Return>

RWTFunctor<Return()> RWTRunnableIOUFunction< Return >::getFunctor

(

)

const

Gets the current functor instance, if any, associated with the runnable.

template<class Return>

static RWTRunnableIOUFunction<Return> RWTRunnableIOUFunction< Return >::make ( )

static

Constructs and returns an RWTRunnableIOUFunction object with an undefined functor. The setFunctor() member must be used to define a functor prior to starting.

template<class Return>

static RWTRunnableIOUFunction<Return> RWTRunnableIOUFunction< Return >::make ( const RWTFunctor< Return()> &  functor )

static

Constructs and returns an RWTRunnableIOUFunction that executes the specified functor when started.

template<class Return>

static RWTRunnableIOUFunction<Return> RWTRunnableIOUFunction< Return >::make ( const RWTIOUEscrow< Return > &  escrow, const RWTFunctor< Return()> &  functor  )

static

Constructs and returns an RWTRunnableIOUFunction that executes the specified functor when started, and places the functor result in escrow.

template<class Return>

RWTIOUResult<Return> RWTRunnableIOUFunction< Return >::operator()

(

)

const

Returns the IOU that will receive the result of the function.

template<class Return >

RWTRunnableIOUFunction< Return > & RWTRunnableIOUFunction< Return >::operator= ( const RWTRunnableIOUFunction< Return > &  second )

inline

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

template<class Return>

RWTIOUResult<Return> RWTRunnableIOUFunction< Return >::result

(

)

const

Returns the IOU that will receive the result of the function.

template<class Return>

void RWTRunnableIOUFunction< Return >::setFunctor

(

const RWTFunctor< Return()> &

functor

)

Sets the functor to be executed by this runnable.

template<class Return>

void RWTRunnableIOUFunction< Return >::setIOUEscrow

(

const RWTIOUEscrow< Return > &

escrow

)

Specifies an IOU escrow that is to receive the result of the function. The new IOU is used until the next time start() is called. Each time an RWTRunnableIOUFunction object is restarted, it checks its current IOU escrow handle to see if it is valid, and if so, checks to see whether the escrow has already been used to capture a result or exception, or has been aborted. If the escrow object is found to be in any of these "redeemable" states, then a new escrow instance is automatically created to capture the next result.