Share via

3.4.1.5 Asynchronous Tasks

  • Article

Certain tasks in VDS can be long-running. The methods that trigger these tasks are asynchronous and have an IVdsAsync interface pointer as an output parameter. When the client calls a method that initiates these tasks, the server creates an async object that implements the IVdsAsync interface and returns the interface pointer to the client in order for it to monitor the task status. (For more information and for examples of how async objects can be used, see section 4.5.) The server maintains this object until the client releases all references to the interface.

For each async object, the server maintains the following information:

Async Output Type: A value of type VDS_ASYNC_OUTPUT_TYPE that indicates the type of task that the async object is monitoring.

  • The server assigns this value when the object is created, and the server does not change it.

Percent Completed: An integer from 0 through 100, which indicates the percentage of progress for the task being completed.

  • This value is initialized to 0 when the object is created.

  • If the task can be subdivided into meaningful progress milestones, the server updates this value after each milestone is passed.

  • The value always increases whenever the value is updated unless the task fails, in which case, the server sets the value to 0.

  • If the task is successfully completed, the server sets the value to 100.

  • When the client calls the IVdsAsync::QueryStatus (Opnum 5) method, the server returns this value in the value that the pulPercentCompleted output parameter references.

Signal State: A Boolean value that indicates whether the task is still in progress (FALSE); or if the task has finished, whether it finished successfully or unsuccessfully (TRUE).

  • This value is initialized to FALSE when the object is created.

  • The server changes the signal state to TRUE when the task fails or when the task successfully completes.

  • If the signal state is TRUE, the server does not change the signal state back to FALSE.

  • If the signal state is FALSE and the client calls the IVdsAsync::Wait (Opnum 4) method, the server blocks the call until the signal state is changed to TRUE, at which point the server unblocks the call and return the results of the task.

  • If the signal state is TRUE and the client calls the IVdsAsync::Wait (Opnum 4) method, the server returns the results of the task immediately.

Return Code: The server returns to the client the HRESULT value that indicates the final result of the task after it completes.

  • The server sets this value when the task fails or when the task successfully completes.

Task-Specific Return Values: Certain tasks need to return information or pointers to objects when they complete.

  • If a task (determined by VDS_ASYNC_OUTPUT_TYPE) returns such values, the server returns these values to the client by means of the VDS_ASYNC_OUTPUT structure that the IVdsAsync::Wait (Opnum 4) method returns after the task is successfully completed.