[libvirt] [PATCHv2 08/13] list: add virDomainListAllSnapshots API

[Peter Krempa]

On 06/15/12 06:18, Eric Blake wrote:
> There was an inherent race between virDomainSnapshotNum() and
> virDomainSnapshotListNames(), where an additional snapshot could
> be created in the meantime, or where a snapshot could be deleted
> before converting the name back to a virDomainSnapshotPtr.  It
> was also an awkward name: the function operates on domains, not
> domain snapshots.  virDomainSnapshotListChildrenNames() suffered
> from the same inherent race, although its naming was nicer.
>
> This patch makes things nicer by grabbing a snapshot list
> atomically, in the format most useful to the user.
>
> * include/libvirt/libvirt.h.in (virDomainListAllSnapshots)
> (virDomainSnapshotListAllChildren): New declarations.
> * src/libvirt.c (virDomainListAllSnapshots)
> (virDomainSnapshotListAllChildren): New functions.
> * src/libvirt_public.syms (LIBVIRT_0.9.13): Export them.
> * src/driver.h (virDrvDomainListAllSnapshots)
> (virDrvDomainSnapshotListAllChildren): New callbacks.
> * python/generator.py (skip_function): Prepare for later
> hand-written versions.
> ---

>   /**
> + * virDomainListAllSnapshots:
> + * @domain: a domain object
> + * @snaps: pointer to variable to store the array containing snapshot objects,
> + *         or NULL if the list is not required (just returns number of
> + *         snapshots)
> + * @flags: bitwise-OR of supported virDomainSnapshotListFlags
> + *
> + * Collect the list of domain snapshots for the given domain, and allocate
> + * an array to store those objects.  Caller is responsible for calling
> + * virDomainSnapshotFree() on each member of the array, then free() on the
> + * array itself.
> + *
> + * By default, this command covers all snapshots; it is also possible to
> + * limit things to just snapshots with no parents, when @flags includes
> + * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS.  Additional filters are provided in
> + * groups, where each group contains bits that describe mutually exclusive
> + * attributes of a snapshot, and where all bits within a group describe
> + * all possible snapshots.  Some hypervisors might reject explicit bits
> + * from a group where the hypervisor cannot make a distinction.  For a
> + * group supported by a given hypervisor, the behavior when no bits of a
> + * group are set is identical to the behavior when all bits in that group
> + * are set.  When setting bits from more than one group, it is possible to
> + * select an impossible combination, in that case a hypervisor may return
> + * either 0 or an error.
> + *
> + * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and
> + * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
> + * have no further children (a leaf snapshot).
> + *
> + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and
> + * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on
> + * whether they have metadata that would prevent the removal of the last
> + * reference to a domain.
> + *
> + * Returns the number of domain snapshots found or -1 in case of error.

See below ...

> + * On success, the array stored into @snaps is guaranteed to have an

>   /**
> + * virDomainSnapshotListAllChildren:
> + * @snapshot: a domain snapshot object
> + * @snaps: pointer to variable to store the array containing snapshot objects,
> + *         or NULL if the list is not required (just returns number of
> + *         snapshots)
> + * @flags: bitwise-OR of supported virDomainSnapshotListFlags
> + *
> + * Collect the list of domain snapshots that are children of the given
> + * snapshot, and allocate an array to store those objects.  Caller is
> + * responsible for calling virDomainSnapshotFree() on each member of the
> + * array, then free() on the array itself.
> + *
> + * By default, this command covers only direct children; it is also possible
> + * to expand things to cover all descendants, when @flags includes
> + * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS.  Also, some filters are provided in
> + * groups, where each group contains bits that describe mutually exclusive
> + * attributes of a snapshot, and where all bits within a group describe
> + * all possible snapshots.  Some hypervisors might reject explicit bits
> + * from a group where the hypervisor cannot make a distinction.  For a
> + * group supported by a given hypervisor, the behavior when no bits of a
> + * group are set is identical to the behavior when all bits in that group
> + * are set.  When setting bits from more than one group, it is possible to
> + * select an impossible combination, in that case a hypervisor may return
> + * either 0 or an error.
> + *
> + * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and
> + * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
> + * have no further children (a leaf snapshot).
> + *
> + * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and
> + * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on
> + * whether they have metadata that would prevent the removal of the last
> + * reference to a domain.
> + *
> + * Returns the number of domain snapshots found or -1 in case of error.

As the new API guarantees to NULL the list on failure I'd state it here 
as I did in the domain list series:

Returns the number of domain snapshots found or -1 and sets snaps to 
NULL in case of error.

> + * On success, the array stored into @snaps is guaranteed to have an
> + * extra allocated element set to NULL, to make iteration easier.
> + */
> +int
>

ACK with the docs fixed.

Peter