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 ?
Regards,
Daniel
--
|: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org -o- http://virt-manager.org :|
|: http://autobuild.org -o- http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list