[libvirt] [PATCH v10 06/19] backup: Introduce virDomainCheckpoint APIs

[Daniel P. Berrangé]

On Wed, Jul 24, 2019 at 12:55:56AM -0500, Eric Blake wrote:
> Introduce a bunch of new public APIs related to backup checkpoints.
> Checkpoints are modeled heavily after virDomainSnapshotPtr (both
> represent a point in time of the guest), although a snapshot exists
> with the intent of rolling back to that state, while a checkpoint
> exists to make it possible to create an incremental backup at a later
> time.  We may have a future hypervisor that can completely manage
> checkpoints without libvirt metadata, but the first two planned
> hypervisors (qemu and test) both always use libvirt for tracking
> metadata relations between checkpoints, so for now, I've deferred
> the counterpart of virDomainSnapshotHasMetadata for a separate
> API addition at a later date if there is ever a need for it.
> 
> Note that until we allow snapshots and checkpoints to exist
> simultaneously on the same domain (although the actual prevention of
> this will be in a separate patch for the sake of an easier revert down
> the road), that it is not possible to branch out to create more than
> one checkpoint child to a given parent, although it may become
> possible later when we revert to a snapshot that coincides with a
> checkpoint.  This also means that for now, the decision of which
> checkpoint becomes the parent of a newly created one is the only
> checkpoint with no child (so while there are APIs for dealing with a
> current snapshot, we do not need those for checkpoints).  We may end
> up exposing a notion of a current checkpoint later, but it's easier to
> add stuff when proven needed than to blindly support it now and wish
> we hadn't exposed it.
> 
> The following map shows the API relations to snapshots, with new APIs
> on the right:
> 
> Operate on a domain object to create/redefine a child:
> virDomainSnapshotCreateXML          virDomainCheckpointCreateXML
> 
> Operate on a child object for lifetime management:
> virDomainSnapshotDelete             virDomainCheckpointDelete
> virDomainSnapshotFree               virDomainCheckpointFree
> virDomainSnapshotRef                virDomainCheckpointRef
> 
> Operate on a child object to learn more about it:
> virDomainSnapshotGetXMLDesc         virDomainCheckpointGetXMLDesc
> virDomainSnapshotGetConnect         virDomainCheckpointGetConnect
> virDomainSnapshotGetDomain          virDomainCheckpointGetDomain
> virDomainSnapshotGetName            virDomainCheckpiontGetName
> virDomainSnapshotGetParent          virDomainCheckpiontGetParent
> virDomainSnapshotHasMetadata        (deferred for later)
> virDomainSnapshotIsCurrent          (no counterpart, see note above)
> 
> Operate on a domain object to list all children:
> virDomainSnapshotNum                (no counterparts, these are the old
> virDomainSnapshotListNames           racy interfaces)
> virDomainSnapshotListAllSnapshots   virDomainListAllCheckpoints
> 
> Operate on a child object to list descendents:
> virDomainSnapshotNumChildren        (no counterparts, these are the old
> virDomainSnapshotListChildrenNames   racy interfaces)
> virDomainSnapshotListAllChildren    virDomainCheckpointListAllChildren
> 
> Operate on a domain to locate a particular child:
> virDomainSnapshotLookupByName       virDomainCheckpointLookupByName
> virDomainSnapshotCurrent            (no counterpart, see note above)
> virDomainHasCurrentSnapshot         (no counterpart, old racy interface)
> 
> Operate on a snapshot to roll back to earlier state:
> virDomainSnapshotRevert             (no counterpart, instead checkpoints
>                                      are used in incremental backups via
> 				     XML to virDomainBackupBegin)
> 
> Signed-off-by: Eric Blake <eblake at redhat.com>
> ---
>  include/libvirt/libvirt-domain-checkpoint.h | 137 +++++
>  include/libvirt/libvirt-domain.h            |   6 +
>  include/libvirt/libvirt.h                   |   5 +-
>  src/conf/virdomainmomentobjlist.h           |   5 +-
>  src/driver-hypervisor.h                     |  38 ++
>  docs/Makefile.am                            |   3 +
>  docs/apibuild.py                            |   2 +
>  docs/docs.html.in                           |   1 +
>  libvirt.spec.in                             |   1 +
>  mingw-libvirt.spec.in                       |   2 +
>  po/POTFILES                                 |   1 +
>  src/Makefile.am                             |   2 +
>  src/libvirt-domain-checkpoint.c             | 567 ++++++++++++++++++++
>  src/libvirt-domain.c                        |  19 +-
>  src/libvirt_public.syms                     |  16 +
>  15 files changed, 796 insertions(+), 9 deletions(-)
>  create mode 100644 include/libvirt/libvirt-domain-checkpoint.h
>  create mode 100644 src/libvirt-domain-checkpoint.c

Reviewed-by: Daniel P. Berrangé <berrange at redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|