RWTRunnableIOUFunction<Return>

Module:  Threads   Package:  Threading

RWTRunnableIOUFunction<Return>   RWRunnable

• Local Index
• Header File
• Description
• Example
• Static Member Functions
• Public Constructors
• Public Destructor
• Public Member Operator
• Public Member Functions
• See Also

Members

getFunctor() make() operator()()

operator=() result() RWTRunnableIOUFunction()

setFunctor() setIOUEscrow() ~RWTRunnableIOUFunction()

#include <rw/thread/RWTRunnableIOUFunction.h> 

The RWTRunnableIOUFunction class is a handle class for a 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, and at that time if the result has not yet been calculated, then the calling thread will block until it has.

Although functors are central to the inner workings of Threading package classes, you may not need to deal with functors directly. Instead, the rwtMakeRunnableIOUFunction() global template functions and macros can build the appropriate functor instance and use it to initialize an RWTRunnableIOUFunction object directly from a function pointer.

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.

One of the effects of this is that callbacks set using the runnable interface of an RWTRunnableIOUFunction and designed to detect the RW_THR_EXCEPTION execution state will not be triggered when the runnable function throws an exception. Another side effect is that, although the runnable terminated because of an exception throw, calling raise() on the runnable will not generate the exception. Instead the IOUResult returned by the function will throw the exception when it is redeemed.

#include <iostream.h>
#include <math.h>
#include <rw/thread/RWTRunnableIOUFunction.h>
#include <rw/thread/RWRunnableServer.h>
#include <rw/thread/rwtMakeRunnableIOUFunction.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(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;
}  

int main()
{
  RWRunnableServer server = RWRunnableServer::make();
  
  RWTRunnableIOUFunction<int> eratosthenes
    = rwtMakeRunnableIOUFunction(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:
  cout << "The greatest prime less than six million is... " 
       << flush;

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

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

/*
 * OUTPUT:
   The greatest prime less than six million is... 5999993
 *
 */

static RWTRunnableIOUFunction<Return>
make();

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

static RWTRunnableIOUFunction<Return>
make(const RWTFunctorR0<Return>& functor)

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

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

Constructs and returns an RWTRunnableIOUFunction that will execute the specified functor when started. The functor result will be stored in escrow.

RWTRunnableIOUFunction()

Constructs an empty RWTRunnableIOUFunction handle instance.

RWTRunnableIOUFunction(const RWTRunnableIOUFunction<Return>& 
                       second)

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

~RWTRunnableIOUFunction();

Destructor.

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

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

RWTIOUResult<Return>
operator()() const;

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

RWTFunctorR0<Return>
getFunctor() const;

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

RWTIOUResult<Return>
result() const;

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

void
setFunctor(const RWTFunctorR0<Return>& functor)

Sets the functor to be executed by this runnable.

void
setIOUEscrow(const RWTIOUEscrow<Return>& escrow)

Specifies an IOU escrow that is to receive the result of the function. The new IOU will not be 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.

rwtMakeRunnableIOUFunction(), RWTFunctorR0, RWRunnable, RWRunnableHandle

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