Asynchronous Method Invocation (AMI) in MATLAB

Asynchronous Method Invocation (AMI) is the term used to describe the client-side support for the asynchronous programming model. AMI supports both oneway and twoway requests, but unlike their synchronous counterparts, AMI requests never block the application. When a client issues an AMI request, the Ice runtime hands the message off to the local transport buffer or, if the buffer is currently full, queues the request for later delivery. The application can then continue its activities and poll or wait for completion of the invocation, or receive a callback when the invocation completes.

AMI is transparent to the server: there is no way for the server to tell whether a client sent a request synchronously or asynchronously.

Future Class

Asynchronous invocations return an instance of the Ice.Future class – the future object. Its API is similar to MATLAB's parallel.future class, in particular, you can call wait and fetchOutputs on this future object.

Asynchronous Exception Semantics

If an invocation throws an exception, the exception will be thrown when the application calls fetchOutputs on the future. The exception is provided by the future, even if the actual error condition for the exception was encountered during the call to the Async method ("on the way out"). The advantage of this behavior is that all exception handling is located with the code that handles the future (instead of being present twice, once where the Async method is called, and again where the future is handled).

There are two exceptions to this rule:

• if you destroy the communicator and then make an asynchronous invocation, the Async method throws Ice.CommunicatorDestroyedException directly.

• a call to an Async method can throw Ice.TwowayOnlyException. An Async method throws this exception if you call an operation that has a return value or out-parameters on a oneway proxy.

Asynchronous Oneway Invocations

You can invoke operations via oneway proxies asynchronously, provided the operation has void return type, does not have any out-parameters, and does not throw user exceptions. If you call an asynchronous proxy method on a oneway proxy for an operation that returns values or throws a user exception, the Async method throws Ice.TwowayOnlyException.

The future returned for a oneway invocation completes as soon as the request is successfully written to the client-side transport. The future completes exceptionally if an error occurs before the request is successfully written.

Flow Control

Asynchronous method invocations never block the thread that calls the Async function : the Ice runtime checks to see whether it can write the request to the local transport. If it can, it does so immediately in the caller's thread. Alternatively, if the local transport does not have sufficient buffer space to accept the request, the Ice runtime queues the request internally for later transmission in the background.

This creates a potential problem: if a client sends many asynchronous requests at the time the server is too busy to keep up with them, the requests pile up in the client-side runtime until, eventually, the client runs out of memory.

You can use future.State to check if a request was sent and implement flow-control for your application.

Canceling an Asynchronous Invocation

You can call cancel on the future returned by an async invocation to cancel this invocation. For example:

futureGreeting = slowGreeter.greetAsync('bob');
pause(4);
futureGreeting.cancel();

Calling this cancel method prevents a queued invocation from being sent or, if the invocation has already been sent, ignores a reply if the server sends one. This cancelation is purely local and has no effect on the server.

Canceling an invocation that has already completed has no effect. Otherwise, a canceled invocation is considered to be completed, meaning the future completed with an Ice.InvocationCanceledException.