Re: [libvirt] API Proposal: virDomainBlockPull() (Block device streaming) V4

Here is version 4 of the BlockStream API (now called BlockPull). Hopefully this version addresses all remaining concerns and I can begin to work on the code. Does everyone approve of the new name 'virDomainBlockPull'? Changes since V3: - Renamed the API to 'Block Pull' to emphasize the effect of the API over its method of operation. - Changed virDomainGetBlockPullInfo() to accept a path argument and to return information about that path alone. - Added a new virDomainEvent to report final status when using CONTINUOUS mode. /* * Block Pull API */ typedef enum { /* * If set, virDomainBlockPull() will operate on the entire device in the * background. The status can be checked and the operation aborted by * using the functions virDomainBlockPullInfo() and * virDomainBlockPullAbort(). */ VIR_DOMAIN_BLOCK_PULL_CONTINUOUS = 1, } virDomainBlockPullFlags; /* 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 * @cursor: pointer to a virDomainBlockPullCursor, or NULL * @flags: One of virDomainBlockPullFlags, or zero * * 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. * * If VIR_DOMAIN_BLOCK_PULL_CONTINUOUS is specified, the entire device will be * streamed in the background. Otherwise, the value stored in @cursor will be * used to stream an increment. * * Returns -1 in case of failure, 0 when successful. On success and when @flags * does not contain VIR_DOMAIN_BLOCK_PULL_CONTINUOUS, the iterator @cursor will * be updated to the proper value for use in a subsequent call. */ int virDomainBlockPull(virDomainPtr dom, const char *path, virDomainBlockPullCursor *cursor, 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 that has been previously started by a call to * virDomainBlockPull() with the VIR_DOMAIN_BLOCK_PULL_CONTINUOUS flag. * * 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 the VIR_DOMAIN_BLOCK_PULL_CONTINUOUS flag set. 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 could be a virDomainBlockPull() without VIR_DOMAIN_BLOCK_PULL_CONTINUOUS and will allow libvirt to manage backing file security regardless of the pull mode used.