Re: [Libvir] RFC: PATCH 2/5: public & driver API for async jobs

This patch adds the public API for the virJobPtr object, and the internal driver support code. The new public APIs are: - int virJobGetInfo(virJobPtr job, virJobInfoPtr info); This gets elapsed time, estimate completion time, completion progress percentage, and completion status - success, failed, cancelled. - virDomainPtr virJobGetDomain(virJobPtr job); If the job was a domain creation attempt, this gets the resulting domain object - virNetworkPtr virJobGetNetwork(virJobPtr job); If the job was a network creation attempt, this gets the resulting network object - virErrorPtr virJobGetNetwork(virJobPtr job); If the job failed, this gets the associated error - int virJobCancel(virJobPtr job); Request that the job be cancelled. This is not an immediate operation. It merely sets a flag, which background jobs will check periodically. So a job may still complete even if it was cancelled. It should be responded to within a few seconds though. - int virJobDestroy(virJobPtr job); Once a job has finished running (success, failed, or cancelled) this may be called to release all resources associated with the job. As mentioned before, the following variants on existing APis are added: - virDomainCreateLinuxJob - virDomainCreateJob - virNetworkCreateJob - virNetworkCreateXMLJob - virDomainSaveJob - virDomainRestoreJob - virDomainDumpCoreJob All are no-ops by default, unless the underlying driver supports async jobs. Finally, the job.c and job.h files provides a set of internal routines to authors for the purpose of managing virJobPtr objects. There is a default impl of the virJobDriver APIs which should be suitable for all existing the remote driver. The async jobs are basically run in a background pthread. This psuedo code illustrates how the 'test' driver might use these to implement an asynchronous variant of the 'save' method. It basically stores the parameters in a struct, and then calls the virJobCreate() method. privdata = malloc(sizeof(*privdata)); if (privdata == NULL) return (NULL); memset(privdata, 0, sizeof(*privdata)); privdata->type = TEST_JOB_DOMAIN_SAVE; privdata->data.save.domidx = domidx; privdata->data.save.path = strdup(path); job = virJobCreate(domain->conn, domain->conn->driver->jobDriver, testDomainSaveWorker, NULL, privdata, VIR_JOB_BOUNDED); The actual work is done in the 'testDomainSaveWorker' method which is passed in to virJobCreate. The job.h file contains APIs for it to call to update progress information and detect cancellation: static void testDomainSaveWorker(virJobPtr job, void *data) { testJobPtr privdata = data; /* A 50 second ETA for saving */ virJobInitialize(job, 50); do { ... do a unit of work... ... Check for cancellation ... if (virJobFinishCancel(job)) return; ... update progress, indicating 1 second of work complete, remove 1 second from the ETA, and add 2% of completion state... virJobUpdateRel(job, 1, -1, 2); } while (...not done...); ... Inform world we're all done ... virJobFinishSuccess(job); } The virJobInitialize, virJobFinishCancel, virJobFinishSuccess and virJobUpdateRel methods all take care to lock the virJobPtr object to ensure thread safety.