[libvirt] RFC New virDomainBlockPull API family to libvirt

[Stefan Hajnoczi]

On Thu, Jul 14, 2011 at 11:19 AM, Jiri Denemark <jdenemar at redhat.com> wrote:
> On Thu, Jul 14, 2011 at 10:58:31 +0100, Stefan Hajnoczi wrote:
>> On Thu, Jul 14, 2011 at 10:21 AM, Jiri Denemark <jdenemar at redhat.com> wrote:
>> > On Wed, Jul 13, 2011 at 15:46:30 -0500, Adam Litke wrote:
>> > ...
>> >> /*
>> >>  * BlockPull API
>> >>  */
>> >>
>> >> /* 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;
>> > ...
>> >> /**
>> >>  * 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 virDomainBlockPull().  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,
>> >>                                               virDomainBlockPullInfoPtr info,
>> >>                                               unsigned int flags);
>> >>
>> >> /**
>> >>  * virConnectDomainEventBlockPullStatus:
>> >>  *
>> >>  * The final status of a virDomainBlockPull() operation
>> >>  */
>> >> typedef enum {
>> >>     VIR_DOMAIN_BLOCK_PULL_COMPLETED = 0,
>> >>     VIR_DOMAIN_BLOCK_PULL_FAILED = 1,
>> >> } virConnectDomainEventBlockPullStatus;
>> >>
>> >> /**
>> >>  * virConnectDomainEventBlockPullCallback:
>> >>  * @conn: connection object
>> >>  * @dom: domain on which the event occurred
>> >>  * @path: fully-qualified filename of the affected disk
>> >>  * @status: final status of the operation (virConnectDomainEventBlockPullStatus
>> >>  *
>> >>  * The callback signature to use when registering for an event of type
>> >>  * VIR_DOMAIN_EVENT_ID_BLOCK_PULL with virConnectDomainEventRegisterAny()
>> >>  */
>> >> typedef void (*virConnectDomainEventBlockPullCallback)(virConnectPtr conn,
>> >>                                                        virDomainPtr dom,
>> >>                                                        const char *path,
>> >>                                                        int status,
>> >>                                                        void *opaque);
>> >
>> > Could these managing functions and event callback become general and usable by
>> > other block operations such as block copy?
>>
>> Hi Jiri,
>> Live block copy will certainly be possible using the streaming API.
>> Before you start streaming you need to use the snapshot_blkdev command
>> to create the destination file with the source file as its backing
>> image.  You can then use the streaming API to copy data from the
>> source file into the destination file.  On completion the source file
>> is no longer needed.
>
> Well, I'm not talking about using the same API for block copy or implementing
> block copy internally as block streaming. I'm talking about making GetInfo,
> Abort and event callback general to be usable not only for block streaming or
> block copy but also for other possible block operations in the future.
>
> The reason is that starting a block operation (streaming, copy, whatever) may
> need different parameters so they should be different APIs. But once the
> operation is started, we just need to know how far it got and we need the
> ability to abort the job. So this can share the same APIs for all operations.
> It doesn't make sense to require any block operation to provide their own set
> of managing APIs.
>
> It's analogous to virDomainSave, virDomainMigrate, virDomainCoreDump. They are
> all different jobs but all of them can be monitored and aborted using
> virDomainGetJobInfo and virDomainAbortJob.

I understand.  I can't comment on libvirt API specifics but yes,
there's a similarity here and a chance we'll have other operations in
the future too.

I'm thinking things like compacting images, compressing images, etc.

Stefan