[libvirt] RFC New virDomainBlockPull API family to libvirt

[Adam Litke]

On 07/14/2011 04:21 AM, Jiri Denemark 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? Also I think it would be nice to
> make the virDomainBlockPullInfo more similar to virDomainJobInfo. I was
> thinking about something along the following lines:

We've already discussed using a JobInfo-like structure in the past but
the fields are not really appropriate for this operation.  The number of
blocks remaining is not available via the qemu API and it is a
non-deterministic value that depends on other guest IO that is ongoing.

> 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.

I don't think we should be supporting multiple block operations at once.


-- 
Adam Litke
IBM Linux Technology Center