Each time a vSphere server runs a method, it creates a Task and a corresponding
TaskInfo data object. Some methods run synchronously and return data as the
Task completes. But methods that end with _Task run asynchronously, and return a reference to a Task that will be created and completed as a processor becomes available. They are created to perform the functions in a non-blocking manner. Therefore, you must use the reference to the
Task to monitor the status and results of the Task. vSphere operations that include the suffix
_Task in their names are asynchronous and return
Task references.
The Task object provides information about the status of the invoked operation through its
TaskInfo data object. An instance of
TaskInfo populates the
info property of the
Task managed object at runtime. By monitoring properties of the
TaskInfo object, a client application can take appropriate action when the
Task completes, or can handle errors if the
Task does not complete successfully.
When a vSphere server creates a Task, it also creates a
TaskEvent object. The
TaskEvent object contains a copy of the
TaskInfo object (
TaskEvent.info). The
TaskEvent copy of the
TaskInfo object is a snapshot of the Task state at the time of its creation. It does not change after it is created. To find the current status of the task, use the
Task.info.eventChainId property.
A Task and its associated objects are session specific, so they will not persist after the session is closed. When your client opens a session, you can only obtain information about the
Task objects that your client is authorized to view.
To cancel a Task that is still running, call the
Task.CancelTask method, passing in the managed object reference to the
Task you want to cancel, as shown in this example:
You can only cancel a Task that has its
cancelable property set to
true and its
state property set to
running. The operation that initiates the
Task sets the value of
cancelable when it creates the
Task. For example, a
CreateVM_Task cannot be cancelled. Before attempting to cancel a running
Task, you can check the values of the
cancelable property and the
state property of the
TaskInfo data object associated with the
Task.
A Task object provides information about the status of the invoked operation through its
TaskInfo data object. An instance of
TaskInfo populates the
info property of the
Task managed object at runtime. By monitoring properties of the
TaskInfo object, a client application can take appropriate action when the
Task completes, or can handle errors if the
Task does not complete successfully.
The Task.info property contains a
TaskInfo data object that contains information about the
Task the server returns to your client application.
When a Task is instantiated by the server, the
TaskInfo.result property is initialized to
Unset. Upon successful completion of an operation, the
result property is populated with the return type specific to the operation. The
result might be a data object, a reference to a managed object, or any other data structure as defined by the operation.
|
1
|
The ClusterComputeResource.AddHost_Task method returns a Task object whose info property contains a TaskInfo data object.
|
Sample TaskInfo Values lists some of the values obtained from a
TaskInfo data object at the beginning and the end of the
Task instantiated by the
CreateVM_Task method.
To monitor the state of a Task, use the
PropertyCollector.WaitForUpdatesEx method. See
Client Data Synchronization (WaitForUpdatesEx). You can monitor the values of
TaskInfo properties, which change as the
Task runs to completion. For example, you can check the values of
startTime,
queueTime,
completeTime,
progress,
result, and
state as the operation progresses. Monitor these properties in your code in a separate thread until the
Task completes, while the main line of your code continues with other activities.
Your code must handle the datatype returned when the Task completes (managed object reference, data object, and so on). In addition to
success,
queued, and
running, an operation can enter an
error state, which your code must handle.
A Task object has a lifecycle that is independent of the
TaskManager that creates it and independent of the entity with which it is associated. It exists to convey status about an operation. You can discard the reference to it when your application no longer needs the information.
Example: Displaying TaskInfoState Values for Tasks in recentTask Array shows a code fragment that obtains values for the
info property from each
Task object in the array.
Example: Sample Run of the TaskList Java Application shows output from a run of the program. See the source code listing for
TaskList.java or for
TaskList.cs in the vSphere Web Services SDK package for details.