19.3 Multithreading and IOUs

The int library is multithread hot and multithread safe. Each protocol request and agent action runs in a separate thread. All of the int library's agent and client methods return RWIOUResults, which are vouchers that can be redeemed for actual results. Using this design, no int library operation ever blocks unless you make it block by redeeming the result before the protocol command has completed its action. The IOU architecture allows you to take advantage of the power of multithreading without having to explicitly handle the synchronization complexities that multithreading introduces.

The following sections provide a brief introduction to using IOUs. Please refer to the Threads.h++ User's Guide and Platform User's Guide for detailed information.

19.3.1 RWIOUResults

RWIOUResults allow a function in one thread to return immediately, while the code that supplies the actual result continues to run in a new thread. The RWIOUResults may be redeemed immediately, as shown in the following example:

RWIFtpReply r = ftp.cwd("pub");

This function actually returns an object of type RWIOUResult<RWIFtpReply>, which is immediately converted to the redeemable type RWIFtpReply. If the redeemable type is available at the time when RWIFtpReply is assigned, the call does not block and the redeemable is returned. If the redeemable is not available yet (that is, the thread processing the request has not finished), then the call blocks in the assignment statement until the redeemable is available.

Under some circumstances, you may opt to do other useful processing while the result is being obtained. In the following example, the result of the cwd method is assigned to an RWIOUResult:

// Get the IOU that will eventually contain the result
RWIOUResult<RWIFtpReply> iou = ftp.cwd("pub");
.
.
.
// Perform other processing
.
.
.
// Redeem the IOU and get the result
RWIFtpReply r = iou; // or RWIFtpReply r = iou.redeem();

The IOU can be redeemed when you are ready to use the result.

19.3.2 RWIOUResult Callbacks

Another mechanism allows you to specify a callback to be invoked when an RWIOUResult becomes redeemable. This gives you the flexibility to perform other useful work while the result is being obtained, with no need to poll the RWIOUResult for its completion status. The following example extends the previous one:

// Get the IOU that will eventually contain the result
RWIOUResult<RWIFtpReply> iou = ftp.pwd("pub");

// Add a callback to the IOUResult that will call our member 
// function when the redeemable is ready.
iou.addCallback(rwIOUMakeCallbackM(myClass, *this, 
  &myClass::getResult, RWIFtpReply));

void
myClass::getResult(RWIOUResult<RWIFtpReply> iou)
{
    // Redeem the IOU and get the result
    RWIFtpReply r = iou;
}

19.3.3 RWIOUResult Polling

RWIOUResult provides a mechanism that allows you to poll the IOU to determine if the result is available. You may then call the redeem method without blocking. For example:

// Get the IOU that will eventually contain the result
RWIOUResult<RWIFtpReply> iou = ftp.pwd("pub");
while (!iou.redeemable()) {
  // Go to sleep for a while, or do other things
}

// Redeem the available IOU result
RWIFtpReply r = iou.redeem();