[libvirt] API Proposal: virDomainBlockPull() V5

[Adam Litke]

Changes since V4:
 - Split out BlockPull() and BlockPullAll().
 - BlockPull() cursor changed to a virDomainBlockPullInfo for progress
   reporting only (from in/out to out-only parameter).

/* An iterator for initiating and monitoring block pull operations */
typedef unsigned long long virDomainBlockPullCursor;

typedef struct _virDomainBlockPullInfo virDomainBlockPullInfo;
struct _virDomainBlockPullInfo {
    /*
     * The following fields provide an indication of block pull progress.  @cur
     * indicates the current position and will be between 0 and @end.  @end is
     * the final cursor position for this operation and represents completion.
     * To approximate progress, divide @cur by @end.
     */
    virDomainBlockPullCursor cur;
    virDomainBlockPullCursor end;
};
typedef virDomainBlockPullInfo *virDomainBlockPullInfoPtr;

/**
 * virDomainBlockPull:
 * @dom: pointer to domain object
 * @path: Fully-qualified filename of disk
 * @pos: A pointer to a virDomainBlockPullInfo structure, or NULL
 * @flags: currently unused, for future extension
 *
 * Populate a disk image with data from its backing image.  Once all data from
 * its backing image has been pulled, the disk no longer depends on a backing
 * image.  This function works incrementally, performing a small amount of work
 * each time it is called.  When successful, @pos is updated with the current
 * progress.
 *
 * Returns -1 in case of failure, 0 when successful.
 */
int                 virDomainBlockPull(virDomainPtr dom,
                                       const char *path,
                                       virDomainBlockPullInfoPtr *pos,
                                       unsigned int flags);

/**
 * virDomainBlockPullAll:
 * @dom: pointer to domain object
 * @path: Fully-qualified filename of disk
 * @flags: currently unused, for future extension
 *
 * Populate a disk image with data from its backing image.  Once all data from
 * its backing image has been pulled, the disk no longer depends on a backing
 * image.  This function pulls data for the entire device in the background.
 * Progress of the operation can be checked with virDomainGetBlockPullInfo() and
 * the operation can be aborted with virDomainBlockPullAbort().  When finished,
 * an asynchronous event is raised to indicate the final status.
 *
 * Returns 0 if the operation has started, -1 on failure.
 */
int                 virDomainBlockPullAll(virDomainPtr dom,
                                          const char *path,
                                          unsigned int flags);

/**
 * virDomainBlockPullAbort:
 * @dom: pointer to domain object
 * @path: fully-qualified filename of disk
 * @flags: currently unused, for future extension
 *
 * Cancel a pull operation previously started by virDomainBlockPullAll().
 *
 * Returns -1 in case of failure, 0 when successful.
 */
int                 virDomainBlockPullAbort(virDomainPtr dom,
                                            const char *path,
                                            unsigned int flags);

/**
 * virDomainGetBlockPullInfo:
 * @dom: pointer to domain object
 * @path: fully-qualified filename of disk
 * @info: pointer to a virDomainBlockPullInfo structure
 * @flags: currently unused, for future extension
 *
 * Request progress information on a block pull operation that has been started
 * with virDomainBlockPullAll().  If an operation is active for the given
 * parameters, @info will be updated with the current progress.
 *
 * Returns -1 in case of failure, 0 when successful.
 */
int                 virDomainGetBlockPullInfo(virDomainPtr dom,
                                              const char *path,
                                              virDomainBlockStreamInfoPtr info,
                                              unsigned int flags);


The following new asynchronous event will be made available for subscription:

VIR_DOMAIN_EVENT_ID_BLOCK_PULL = 7,

typedef enum {
    VIR_DOMAIN_BLOCK_PULL_COMPLETED,
    VIR_DOMAIN_BLOCK_PULL_FAILED,
} virConnectDomainEventBlockPullStatus;

typedef void (*virConnectDomainEventBlockPullCallback(virConnectPtr conn,
                                                      virDomainPtr dom,
                                                      const char *path,
                                                      int status);

Upon receipt of this event and when the status field indicates success, libvirt
will revoke access to the backing file which is no longer needed by the domain.

NOTE: Qemu will emit an asynchronous event (VIR_DOMAIN_BLOCK_PULL_COMPLETED)
after any operation that eliminates the dependency on the backing file.  This 
will allow libvirt to manage backing file security.  If the operation failed,
an event (VIR_DOMAIN_BLOCK_PULL_FAILED) will indicate that the backing file has
not been removed.

-- 
Adam Litke
IBM Linux Technology Center