The Asynchronous API
All generated proxies contain both synchronous and 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 that 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.
NOTE >> It is important to understand that your client must wait for the transport to return from the 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.
Using the Asynchronous API
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. The client implementations generated by HydraExpress use the method that includes
rwsf::CallInfo because it simplifies coding if you want to modify the message handling such as by adding headers to the message.
• Three asynchronous methods, including two <methodName>Start() methods, and a <methodName>End() method, as follows:
rwsf::AsyncHandle <methodName>Start(
const std::string& input_in);
rwsf::AsyncHandle <methodName>Start(
rwsf::CallInfo& callInfo,
const std::string& input_in);
std::string <methodName>End(rwsf::AsyncHandle& handle);
The
<methodName>Start() method sends the request to the server and receives an
rwsf::AsyncHandle object in return. The handle’s method
isFinished() may then be used to poll for whether the response is available.
Like for the synchronous methods, the generated client implementation again uses the variant of
<methodName>Start() with
rwsf::CallInfo, and for the same reason.
Call the
<methodName>End() method to obtain the response, passing in the
rwsf::AsyncHandle object received from
<methodName>Start(). If the response is not ready, the
<methodName>End() method blocks. There is no way to prematurely abort the operation and free its resources. You must wait for the operation to complete.
