Closing an IOU
In the Interthread Communication package, the act of storing or writing the result of an operation into an IOU is called
closing the IOU. To close an IOU, you must possess an
RWTIOUEscrow handle that references the IOU escrow object.
The
RWTIOUEscrow class has two functions related to closing an IOU:
• close()
• setException()
The close() Function
The close() function stores the final result of an operation into the IOU object. It releases any threads that have been waiting for the result.
RWTIOUEscrow also has a function operator called
operator()() and an assignment operator called
operator=() that have the same capability as the
close() function. Given that “iou” is an instance of the
RWTIOUEscrow class, the following statements are functionally identical:
iou.close(value);
iou(value);
iou = value;
The setException() Function
RWTIOUEscrow has two versions of the
setException() function. Both indicate whether or not the operation failed to produce a result due to an error condition. One version of the function accepts a reference to an instance of the base exception class,
RWTHRxmsg. The other version accepts an
RWCString message that is used internally to initialize an
RWTHRxmsg instance. In either case, these functions:
• Release threads that are waiting for a result.
• Cause the exception to be rethrown in those threads.
Example
Typical uses of the
close() and
setException() functions are shown in the code fragment in
Example 44.
Example 44 – Closing an IOU
void async_operation(RWTIOUEscrow<int>& iou)
{
try {
int result=0;
// Perform some operation to calculate result...
// Close the escrow
iou.close(result);
}
catch(...) {
iou.setException("Unexpected Exception");
}
}
The IOU object is intended as a “one-shot” communication mechanism. An IOU instance can only be closed once during its life-span—it is not possible to reset or reuse an IOU. Any attempt to do so produces an RWTHREscrowAlreadyClosed exception.
The
RWTIOUEscrow class also has several functions that applications can call to query the status of an IOU object:
• aborted() — Returns true if a client has requested that the operation be aborted.
• closeable() — Returns true if the IOU has not been aborted and has not yet been closed.
• closed() — Returns true if the IOU has been closed.
• inError() — Returns true if the IOU was closed using setException().
• redeemed() — Returns true if any thread has successfully redeemed the IOU to retrieve its value.