[libvirt] [PATCH 6/8] backup: Introduce virDomainBackup APIs

[Kashyap Chamarthy]

On Wed, Jun 13, 2018 at 11:42:27AM -0500, Eric Blake wrote:
> Introduce a few more new public APIs related to incremental backups.
> This builds on the previous notion of a checkpoint (without an
> existing checkpoint, the new API is a full backup, differing only
> from virDomainCopy in the point of time chosen); and also allows
> creation of a new checkpoint at the same time as starting the backup
> (after all, an incremental backup is only useful if it covers the
> state since the previous backup).  It also enhances event reporting
> for signaling when a push model backup completes (where the
> hypervisor creates the backup); note that the pull model does not
> have an event (starting the backup lets a third party access the
> data, and only the third party knows when it is finished).

First, thanks for the work!  (And for doing the detailed write-ups, as
is your wont.)

A super minor note: I hope you'll also add the API names in the commit
message itself (like you did in the past, for the older APIs); it will
be handy when browsing `git log` later.

So far I see the new APIs are:

    - virDomainBackupBegin()
    - virDomainBackupGetXMLDesc()
    - virDomainBackupEnd()

So, OpenStack Nova currently still uses virDomainBlockRebase(); it
hasn't even moved to the newer virDomainBlockCopy().  But as we know,
currently both of them have the limitation of having to undefine and
then re-define the guest XML.

As you suggested elsewhere, probably I could explore (once they are
'frozen') moving to these proposed APIs, which will work without having
to do the undefine + re-define dance.

> Signed-off-by: Eric Blake <eblake at redhat.com>
> ---
>  include/libvirt/libvirt-domain-checkpoint.h |  11 ++
>  include/libvirt/libvirt-domain.h            |  14 +-
>  src/driver-hypervisor.h                     |  14 ++
>  src/libvirt-domain-checkpoint.c             | 200 ++++++++++++++++++++++++++++
>  src/libvirt-domain.c                        |   8 +-
>  src/libvirt_public.syms                     |   3 +
>  tools/virsh-domain.c                        |   3 +-
>  7 files changed, 249 insertions(+), 4 deletions(-)
> 
> diff --git a/include/libvirt/libvirt-domain-checkpoint.h b/include/libvirt/libvirt-domain-checkpoint.h
> index 4a7dc73089..c1d382fddc 100644
> --- a/include/libvirt/libvirt-domain-checkpoint.h
> +++ b/include/libvirt/libvirt-domain-checkpoint.h
> @@ -144,4 +144,15 @@ int virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
>  int virDomainCheckpointRef(virDomainCheckpointPtr checkpoint);
>  int virDomainCheckpointFree(virDomainCheckpointPtr checkpoint);
> 
> +/* Begin an incremental backup job, possibly creating a checkpoint. */
> +int virDomainBackupBegin(virDomainPtr domain, const char *diskXml,
> +                         const char *checkpointXml, unsigned int flags);
> +
> +/* Learn about an ongoing backup job. */
> +char *virDomainBackupGetXMLDesc(virDomainPtr domain, int id,
> +                                unsigned int flags);
> +
> +/* Complete an incremental backup job. */
> +int virDomainBackupEnd(virDomainPtr domain, int id, unsigned int flags);

[...]

-- 
/kashyap