Asynchronous API Calls and Task Polling
Availability of Asynchronous API functions
Asynchronous API functions have been a feature of the Java and C# APIs for many versions of XenServer. Starting with XenServer 6.1 we augmented the C API functions to also provide asynchronous support. We realised we that it might be useful to provide a code example demonstrating the availability of the asynchronous functionality. This example isn't yet bundled into main code examples but will be in future releases of XenServer, however we thought it might be useful to make it available here in the meantime.
The code example itself is for an asynchronous migration of VMs. test_vm_async_migrate.c
If you have already downloaded the XenServer C API bindings you should add this code example to the /test/ directory where the other code examples such as test_vm_ops.c are.
What is an asynchronous API function
The functions documented in the API documentation are usually synchronous functions - when you call them, your program has to wait for XenServer to finish the call and for XenServer to return control to your code. If a call is by its nature slow or you want to cancel it, you would have to wait or have incorporated some sort of threading in your own code. Asynchronous API calls return control to your code after starting the functionality called, returning you a task that can be polled in your code at a later time. This means that you can start off many different tasks in quick succession.
When a particular call has finished executing, the task will contain information on the success of the task and (if appropriate) the returned information that would have been returned by the regular synchronous function.
Tasks are designed to be polled, questioned as to how far the operation has progressed. In the code example the task status is regularly checked to see how the operation has progressed; whether it is still pending, has failed or has succeeded.
The user can choose to cancel a task that is still pending, in the C API the functions xen_task_cancel and xen_task_cancel_async are available.
Where are asynchronous API functions documented?
The asynchronous functions are direct equivalents of the regular synchronous API functions. As such we don't explicitly document them. The rational is that because their format is standard it would increase the documentation with duplicated information.
When should I use asynchronous API calls?
For operations that would be expected to take a significant length of time, e.g. a VM migration or snapshot, we would generally recommend using an asynchronous call. For fast API calls, e.g. rapid read-only queries, the user may prefer to use synchronous calls.
Asynchronous applications - anything else worth knowing?
If you decide to use asynchronous APIs in your application, it is very likely that you will also find events. See SDK User Guide, in section 4.1.6. Subscribing to and listening for events.
Other useful background information
- The SDK User Guide contains another description of an asynchronous algorithm using tasks, that implements a progress bar, in section 4.1.5. "Using tasks to manage asynchronous operations"