Redeeming an IOU
The act of reading a result from an IOU is called
redeeming the IOU. To redeem an IOU, you must possess an
RWTIOUResult handle that references the IOU escrow object.
The
RWTIOUResult class has three functions for redeeming the IOU:
• A function operator operator()().
• A conversion operator operator Redeemable().
• A redeem() function.
These three members perform an identical function. Given that
iou is an instance of the
RWTIOUResult class, the following statements are functionally equivalent:
value = iou();
value = iou;
value = iou.redeem();
Rules about Threads and IOUs
Threads use IOUs in the following ways:
• Threads attempting to redeem an IOU that has not been closed, block until another thread writes a result or exception to the IOU object.
• If an IOU is closed with an exception, any attempt to redeem the IOU produces that exception:
try {
result = iou.redeem();
cout << "Operation succeeded! " << result << endl;
}
catch(RWException& msg) {
cout << "Operation failed! " << msg.why() << endl;
}
• A thread can redeem an IOU as many times as it wants.
• An IOU can be shared between and redeemed by any number of threads.
Aborting a Request
The RWTIOUResult::abort() member can be used to signal that the IOU client no longer needs the result represented by the IOU. This function simply sets a flag within the IOU, so that it can be polled by another thread.
Querying the Status of an IOU Object
The
RWTIOUResult class also has several functions that can be used to query the status of an IOU object:
• aborted() — Returns true if a client has requested that the operation be aborted.
• inError() — Returns true if the IOU was closed using setException().
• redeemable() — Returns true if the IOU has been closed, either with a value or with an exception.
• redeemed() — Returns true if any thread has successfully redeemed the IOU to retrieve its value.