[libvirt] RFC New virDomainBlockPull API family to libvirt

[Jiri Denemark]

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? Also I think it would be nice to
make the virDomainBlockPullInfo more similar to virDomainJobInfo. I was
thinking about something along the following lines:

typedef struct _virDomainBlockJobInfo virDomainBlockJobInfo;
struct _virDomainBlockJobInfo {
    int job; /* BLOCK_PULL, BLOCK_COPY, ... */
    int status; /* COMPLETED, FAILED, CANCELLED */
    unsigned long long timeElapsed;
    unsigned long long total;
    unsigned long long processed;
    unsigned long long remaining;
}

int virDomainBlockJobAbort(virDomainPtr dom,
                           const char *path,
                           unsigned int flags);

int virDomainGetBlockJobInfo(virDomainPtr dom,
                             const char *path,
                             virDomainBlockJobInfoPtr info,
                             unsigned int flags);

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

I doubt it's practical to support more than one block operation on a single
disk at a time, since that sounds to me like asking for troubles and data
corruption. But if someone thinks we should keep the door open for this, we
can add 'job' parameter to Abort and Info APIs.

What do you thing about that?

Jirka