RWTIOUResult<Redeemable>

Module:  Threads   Package:  Interthread Communication

RWTIOUResult<Redeemable>   RWTEscrowHandle<Redeemable>

• Local Index
• Header File
• Description
• Example
• Public Typedefs
• Public Constructors
• Public Destructor
• Public Member Operators
• Public Member Functions
• See Also

Members

abort() aborted() addCallback() inError()

operator Redeemable() operator()() operator=() redeem()

redeemable() RedeemableType redeemed() removeCallback()

RWTIOUResult() RWTIOUResultCallback ~RWTIOUResult()

#include <rw/itc/RWTIOUResult.h> 

An RWTIOUResult<Redeemable> is a readable IOU handle. An IOU, sometimes known as a future, is a promise for a value that is forthcoming. It is a placeholder for that value. Usually the writer of an IOU and the reader (or readers) of an IOU are in different threads of control. In this sense IOUs are a mechanism for interthread communication.

The template parameter Redeemable is the value type of IOU result. This type must provide a public copy-constructor and must allow dynamic allocation using operator new().

An IOU is a write once/read many structure. It may only be written to once, but may be read any number of times.

The RWTIOUResult<Redeemable> handle is a reference counted handle to an RWTEscrowImp<Redeemable>. It can be copied and passed by value. When the last handle to a given RWTEscrowImp<Redeemable> is destroyed, then the internal RWTEscrowImp<Redeemable> is destroyed.

An RWTIOUResult<Redeemable> can be initialized by or assigned to an RWTIOUEscrow<Redeemable>, and visa versa. Both are interfaces to the same underlying RWTIOUEscrowImp<Redeemable>. RWTIOUResult<Redeemable> is a read interface, and RWTIOUEscrow<Redeemable> is a write interface.

The holder of the RWTIOUResult<Redeemable> decides how and when to redeem the value held by the IOU. IOU redemption is the process of getting the result from the IOU when it is available. There are 3 ways to redeem an RWTIOUResult<Redeemable>:

• Blocking. A call to RWTIOUResult<Redeemable>::redeem() will block the caller until the result is available.

• Polling. Calls to RWTIOUResult<Redeemable>::redeemable() return whether the IOU is redeemable. An IOU is redeemable if a value has been set, an exception has been set, or the IOU has been aborted.

• Callback. A callback function may be registered with the IOU using RWTIOUResult<Redeemable>::addCallback(). The callback function is created using one of the rwtMakeIOUCallback() functions or macros. The callback is called and passed an RWTIOUResult<Redeemable> when the IOU is redeemable.

An IOU may be aborted by the holder of an RWTIOUResult<Redeemable>. This will cause an exception to be thrown if an attempt is made to redeem the IOU or to set its value.

Similarly an exception may be set on an IOU by the holder of an RWTIOUEscrow<Redeemable>. This will cause the exception to be thrown when an attempt is made to redeem it.

An RWTIOUResult<Redeemable> is redeemable if a value has been set, if it has been aborted, or if an exception has been set.

#include <rw/thread/RWTThreadIOUFunction.h> // for
                                         // RWTThreadIOUFunction
#include <rw/itc/rwtMakeIOUCallback.h> // for rwtMakeIOUCallback
#include <rw/itc/RWTIOUResult.h> // for RWTIOUResult<Redeemable>
#include <rw/thread/RWRunnableSelf.h>         // for ::rwSleep()

int sixteen(void)
{
   ::rwSleep(500); // simulate useful activity
   return 16;
}

void callback(RWTIOUResult<int> intIOUResult) {
   try {
      int val = intIOUResult;  // redeem value
      cout << "callback received value of " << val << endl;
   }
   catch (...) { cout << "something bad happened" << endl; }
}

int main()
{
   try {
      RWTThreadIOUFunction<int> thread;
      thread = rwtMakeThreadIOUFunction(sixteen);
      RWTIOUResult<int> iouRes = thread.result(); // get
                                                 // RWTIOUResult

      // register callback
      iouRes.addCallback(rwtMakeIOUCallback(callback));

      thread.start();

      // poll until redeemable
      while (!iouRes.redeemable()) ::rwSleep(50);

      // redeem RWTIOUResult
      cout << "redeemed " << iouRes.redeem() << endl;
   }
   catch (...) {
      cout << "something bad happened" << endl;
   }
   return 0;
}

typedef Redeemable RedeemableType;
typedef RWTFunctor1<RWTEscrowHandle<Redeemable> RWTIOUResultCallback;

RWTIOUResult();

Creates an empty, invalid handle. Use of an instance created by the default constructor will result in an RWTHRInvalidPointer exception being thrown. You can determine if an RWTIOUResult<Redeemable> handle is valid by calling the isValid() member function which is inherited from the RWHandleBase base class.

RWTIOUResult(const RWTEscrowHandle<Redeemable>& escrowHandle);

Constructs a new handle instance and attaches it to the escrow instance, if any, pointed to by second, and increments the escrow's reference count. This constructor allows an RWTIOUEscrow<Redeemable> to be constructed from an RWTIOUResult<Redeemable>.

RWTIOUResult(const RWTIOUResult<Redeemable>& second);

Copy constructor. Constructs a new handle instance and attaches it to the escrow instance, if any, pointed to by second, and increments the escrow's reference count.

~RWTIOUResult()

Destroys the handle and decrements the reference count of the current escrow instance, if any, deleting the escrow if its reference count reaches zero.

RWTIOUResult<Redeemable>&
operator=(const RWTIOUResult<Redeemable>& second)

Detaches this handle from its current escrow instance, if any, decrementing the escrow's reference count and deleting the escrow if the count reaches zero. It then attaches to the escrow instance, if any, pointed by second, and increments the new escrow's reference count.

Redeemable
operator()() const;

Equivalent to redeem().

operator Redeemable() const;

Equivalent to redeem().

void
abort() const;

Tells the writer of an IOU that a result is no longer needed. Notifies anyone waiting to redeem the IOU so they can detect, abort, and catch an exception. Subsequent calls to redeem the IOU will immediately receive an exception indicating that the operation associated with the IOU has been aborted. Ignored if the operation was already aborted. Possible exceptions include RWTHRInvalidPointer.

bool
aborted() const;

Returns true if the operation has been aborted, and false if not. Possible exceptions include RWTHRInvalidPointer.

void
addCallback(const RWTIOUResultCallback& callback)

Adds a callback. Will be called when the IOU is closed.

bool
inError() const;

Returns true if the IOU was closed with an error, and false if not. Possible exceptions include RWTHRInvalidPointer.

Redeemable
redeem() const;

Gets the result, blocking if the result is not yet available. Throws RWTHROperationAborted if the IOU (or the associated operation) has been aborted. If an exception is thrown and stored in the IOU, then that exception is re-thrown by this routine.

bool
redeemable() const;

Returns true if the IOU has been closed, closed with an error, or aborted, and false if not. This function is used to poll an IOU for the availability of a result. Possible exceptions include RWTHRInvalidPointer.

bool
redeemed() const;

Returns true if the IOU has been redeemed at least once, and false if the IOU has never been redeemed. Possible exceptions include RWTHRInvalidPointer.

void
removeCallback(const RWTIOUResultCallback& callback);

Removes callback. If callback does not exist, this does nothing.

RWTIOUEscrow<Redeemable>, RWTEscrowHandle<Redeemable>, RWTEscrowImp<Redeemable>, RWTThreadEscrowImp<Redeemable>, rwtMakeIOUCallback()

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