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@xxxxxxxxxx> > --- > 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@xxxxxxxxxx> 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 :| -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
