VIX API Concepts : Monitoring a Job Object

Monitoring a Job Object

Currently, a client application can use several mechanisms to detect when a job object has been signaled:

• Poll the job, by calling a non-blocking function that checks whether it has been signaled. This is described in Polling the Job Object for Completion.
• Block until the job is signaled, by calling the VixJob_Wait() function. This is described in Using the Job Object to Block Calls.
• Register a callback function that is called when the job is signaled. This is described in Using a Callback Function.

A typical asynchronous call looks similar to VixVM_Open(), and there are several common patterns shared by all asynchronous Vix calls. For reference, the following code shows the signature of VixVM_Open().

VixHandle VixVM_Open(VixHandle hostHandle,
                     const char *vmxFilePathName,
                     VixEventProc *callbackProc,
                     void *clientData);

This function creates a Vix job object and returns a VixHandle for this new job object. The caller is responsible for releasing this job object, even if the job object is not used for anything else.

Polling the Job Object for Completion

The job object tracks the status of an asynchronous operation. You can interrogate the completion status of a job object using the function VixJob_CheckCompletion(). This is a non-blocking function that returns a Boolean value representing the completion state of the asynchronous operation. The following example shows the use of VixJob_CheckCompletion() in a polling loop.

1. Example 2-10.

Bool OpenVMWithPolling(const VixHandle hostHandle,
                       const char *vmName,
                       VixHandle *vmHandle)
{
   VixError err = VIX_OK;
   VixHandle jobHandle = VIX_INVALID_HANDLE;
   Bool completed = FALSE;
   
   if (!vmHandle) {
      return FALSE;
   }
   *vmHandle = VIX_INVALID_HANDLE;
 
   // Start asynchronous operation.
   jobHandle = VixVM_Open(hostHandle,
                          vmName,
                          NULL, // callbackProc,
                          NULL); // clientData
         
   // Poll the job object for completion of asynchronous operation.
   while ( !completed ) {
      sleep(1);
      
      err = VixJob_CheckCompletion(jobHandle, &completed);
      if (VIX_OK != err) {
         Vix_ReleaseHandle(jobHandle);
         return FALSE;
      }
   }
   
   err = Vix_GetProperties(jobHandle,
                           VIX_PROPERTY_JOB_RESULT_HANDLE,
                           vmHandle,
                           VIX_PROPERTY_NONE);
   if (VIX_OK != err) {
      Vix_ReleaseHandle(jobHandle);
      *vmHandle = VIX_INVALID_HANDLE;
      return FALSE;
   }
   
   Vix_ReleaseHandle(jobHandle);
   return TRUE;
   // Caller must release vmHandle.
}

Using the Job Object to Block Calls

The job object allows a client to block until an asynchronous call completes. This achieves the same result as if the asynchronous call were a synchronous call. Here is an example of how this can be done, using the VixJob_Wait() function.

1. Example 2-11.

VixHandle hostHandle = VIX_INVALID_HANDLE;
VixHandle jobHandle = VIX_INVALID_HANDLE;
VixHandle vmHandle = VIX_INVALID_HANDLE;
 
jobHandle = VixHost_Connect(VIX_API_VERSION,
                            VIX_SERVICEPROVIDER_VMWARE_VI_SERVER,
                            "https://server2.example.com/sdk", // hostName
                            0, // hostPort
                            "root", // username
                            "secretpw", // password
                            0, // options
                            VIX_INVALID_HANDLE, // propertyListHandle
                            NULL, // callbackProc
                            NULL); // clientData
 
// Wait for completion of operation.
err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   goto abort;
}
 
// Release handle when done.
Vix_ReleaseHandle(jobHandle);
jobHandle = VIX_INVALID_HANDLE;

Retrieving Results from Job Object Properties

The job object can also be used to retrieve results from an asynchronous operation once the asynchronous operation has completed. You can get these properties by calling Vix_GetProperties() on the job handle. The following example shows how this is done.

1. Example 2-12.

VixHandle hostHandle = VIX_INVALID_HANDLE;
VixHandle jobHandle = VIX_INVALID_HANDLE;
VixHandle vmHandle = VIX_INVALID_HANDLE;
 
jobHandle = VixHost_Connect(VIX_API_VERSION,
                            VIX_SERVICEPROVIDER_VMWARE_VI_SERVER,
                            "https://server2.example..com/sdk", // hostName
                            0, // hostPort
                            "root", // username
                            "secretpw", // password
                            0, // options
                            VIX_INVALID_HANDLE, // propertyListHandle
                            NULL, // callbackProc
                            NULL); // clientData
 
// Wait for completion of operation.
err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   goto abort;
}
 
// Collect desired result of operation.
err = Vix_GetProperties(jobHandle, 
                        VIX_PROPERTY_JOB_RESULT_HANDLE,
                        &hostHandle,
                        VIX_PROPERTY_NONE);
 
// Release handle when done.
Vix_ReleaseHandle(jobHandle); 
jobHandle = VIX_INVALID_HANDLE;

For convenience, you can also extract properties from the job object with the VixJob_Wait() function. The following example shows how this is done.

1. Example 2-13.

// Start asynchronous operation.
jobHandle = VixVM_Open(hostHandle,
                       "[standard] WindowsXP/WindowsXP.vmx",
                       NULL, // callbackProc
                       NULL); // clientData
 
// Wait for completion of operation. Collect result handle.
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &vmHandle,
                  VIX_PROPERTY_NONE);
 
// Release handle when done.
Vix_ReleaseHandle(jobHandle); 
jobHandle = VIX_INVALID_HANDLE;

For simplicity, most of the examples in this document use the approach of calling VixJob_Wait() and requesting the desired properties at the same time. Some kinds of applications might increase responsiveness by using callback functions in a multithreaded client.