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

On Mon, May 23, 2011 at 11:56:03AM -0500, Adam Litke wrote: > 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. I assume it will also emit VIR_DOMAIN_BLOCK_PULL_FAILED when a continuous streaming operation aborts, because in that case you obviously still have the backing file present so PULL_COMPLETED wouldn't be issued ?