13.2 The Asynchronous API

All generated proxies contain both synchronous or asynchronous service operation methods. When you use the proxy, you simply select either the synchronous or the asynchronous method.

The asynchronous methods return an instance of rwsf::AsyncHandle. This class launches a thread which runs the operation, and the response blocks until it is ready. While the method is running, the main thread does not block and is free to perform other tasks.

An asynchronous client can make multiple asynchronous calls on the proxy. Each call uses a single transport with a single connection to the server. This design gives you full control over transport creation and avoids the case in which multiple transports are created automatically outside of your control. However, your client must wait for the transport to return from a previous operation before the next one is sent to the server.

To achieve full asynchronous behavior, you may want to create separate proxies, so that each one has its own connection to the server.

The asynchronous class architecture is illustrated in Figure 7.

Figure 7: Architecture for asynchronous clients

For each operation defined in the WSDL, the code generator creates five service operation methods to choose from when implementing the client. These include:

• Two synchronous methods, one taking a rwsf::CallInfo object as a parameter, and one without, as follows:

std::string <methodName>(const std::string& input_in);
std::string <methodName>(rwsf::CallInfo& callInfo, 
                         const std::string& input_in);

If you are creating a synchronous client, choose one of these methods to implement in the invoke<methodName>() method of the client. Generally, there is no need to pass a callInfo object unless you are including customized headers or handlers with your message.

• Three asynchronous methods, including two start() methods, and an end() method, as follows:

rwsf::AsyncHandle <methodName>Start(
                              const std::string& input_in);
rwsf::AsyncHandle <methodName>Start(
                              const rwsf::CallInfo& callInfo,
                              const std::string& input_in);

The start() method sends the request to the server and receives a rwsf::AsyncHandle object in return. The handle's method isFinished() may then be used to poll for whether the response is available.

Once again, the method with a callInfo parameter is available for custom processing.

std::string <methodName>End(rwsf::AsyncHandle& handle);

Call the End() method to obtain the response, passing in the rwsf::AsyncHandle object received from Start(). If the response is not ready, the End() method will block.

© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.