Multithreading and IOUs

Internet Protocols Module User's Guide
Rogue Wave web site: Home Page | Main Documentation Page

2.4 Multithreading and IOUs

The packages are multithread-hot and multithread-safe, which means that they create threads to complete their tasks. Each protocol request and agent action runs in a separate thread. The packages handle thread creation, management, and synchronization for you using the Threads Module of SourcePro Core.

The packages use Threads Module IOUs to allow asynchronous communication. All of the agent and client methods return RWTIOUResults, which are vouchers that can be redeemed for actual results. This means that operations never block unless you make them block by redeeming the result before the protocol command has completed its action. The IOU architecture enables you to use multithreading without explicitly handling the synchronization complexities that multithreading introduces.

The following sections briefly describe how to use IOUs. For more information, see the Threads Module User's Guide and the Threads Module Platform Guide.

2.4.1 RWTIOUResults

RWTIOUResults 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 RWTIOUResults may be redeemed immediately, as shown in the following example:

RWFtpReply r = ftp.cd("pub");

This function actually returns an object of type RWTIOUResult<RWFtpReply>, which is immediately converted to the redeemable type RWFtpReply. If the redeemable type is available at the time when RWFtpReply 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 want your application to do other processing instead of waiting until the result is received. In the following example, the result of the cd method is assigned to an RWTIOUResult:

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

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

2.4.2 RWTIOUResult Callbacks

You can define a callback that is invoked when an RWTIOUResult becomes redeemable. The callback enables your application to perform other work instead of waiting for the result and without polling the RWTIOUResult for its completion status. The following example extends the previous example:

// Get the IOU that will eventually contain the result
RWTIOUResult<RWFtpReply> iou = ftp.cd("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,
                                   RWFtpReply));

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

2.4.3 RWTIOUResult Polling

RWTIOUResult enables your application to poll the IOU to determine if the result is available. You can then call the redeem() method without blocking, as shown in the following example.

// Get the IOU that will eventually contain the result
RWTIOUResult<RWFtpReply> iou = ftp.cd("pub");

while (!iou.redeemable()) {
  // Go to sleep for a while, or do other things
}

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

2.4.4 A Common Multithreading Mistake

When a new thread is created to handle the dataClose() method, the main thread may exit earlier than the new thread, which results in undesirable behavior when the new thread exits.

Although this software attempts to hide multithreading programming issues, your application must handle this situation.

The solution is shown in the example below. Line //1 ensures that the new thread exits before the main thread goes out of scope, by forcing the IOU to be redeemed. This blocks the main thread until the dataClose() operation has completed.

void main()
{
  RWFtpClient client;
  ...
  // do file transfer processing
  ...
  // incorrect !!!
  client.dataClose(); 
  // instead, use RWFtpReply reply = client.dataClose();       //1
  // or assign to IOU and use the callback mechanism
  // or assign to IOU and use the polling mechanism
}

The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.