[libvirt] [PATCH 03/49] list: Define new API virStorageListALlStoragePools

[Eric Blake]

On 07/20/2012 08:24 AM, Osier Yang wrote:
> This introduces a new API to list the storage pool objects,
> 4 groups of flags are provided to filter the returned pools:
> 
>   * Active or not
> 
>   * Autostarting or not
> 
>   * Persistent or not
> 
>   * And the pool type.
> 
> include/libvirt/libvirt.h.in: New enum virConnectListAllStoragePoolFlags;
>                               Declare the API.
> python/generator.py: Skip the generating
> src/driver.h: (virDrvConnectListAllStoragePools)
> src/libvirt.c: Implementation for the API.
> src/libvirt_public.syms: Export the symbol.

> +++ b/include/libvirt/libvirt.h.in
> @@ -2471,6 +2471,38 @@ int                     virConnectListDefinedStoragePools(virConnectPtr conn,
>                                                            int maxnames);
>  
>  /*
> + * virConnectListAllStoragePoolsFlags:
> + *
> + * Flags used to filter the returned pools. Flags in each group
> + * are exclusive attribute for a pool.

In virConnectListAllDomainsFlags, we used a different wording:

Flags used to tune pools returned by virConnectListAllStoragePools().
Note that these flags come in groups; if all bits from a group are 0,
then that group is not used to filter results.

> +++ b/src/libvirt.c
> @@ -11215,6 +11215,83 @@ virStoragePoolGetConnect (virStoragePoolPtr pool)
>  }
>  
>  /**
> + * virConnectListAllStoragePools:
> + * @conn: Pointer to the hypervisor connection.
> + * @pools: Pointer to a variable to store the array containing storage pool
> + *         objects or NULL if the list is not required (just returns number
> + *         of pools).
> + * @flags: bitwise-OR of virConnectListAllStoragePoolsFlags.
> + *
> + * Collect the list of storage pools, and allocate an array to store those
> + * objects. This API solves the race inherent between virConnectListStoragePools
> + * and virConnectListDefinedStoragePools.

It would also be worth enhancing the documentation of those two
functions to point out the race, and cross-reference to this function.
For a prior example, see how commit 747f64ee did things.

> + *
> + * By default, this API covers all storage pools; it is also possible
> + * to return the filtered objects with flags. Filters are provided in groups,
> + * where each group contains bits that describe mutually exclusive attributes
> + * of a storage pool.

The wording in the prior example was:

Normally, all storage pools are returned; however, @flags can be used to
filter the results for a smaller list of targeted pools.  The valid
flags are divided into groups, where each group contains bits that
describe mutually exclusive attributes of a pool, and where all bits
within a group describe all possible pools.

> + *
> + * The first group of @flags is VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE and
> + * VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE to fitler the pools by state.

s/fitler/filter/


> @@ -11256,9 +11333,11 @@ error:
>   * @names: array of char * to fill with pool names (allocated by caller)
>   * @maxnames: size of the names array
>   *
> - * Provides the list of names of active storage pools
> - * upto maxnames. If there are more than maxnames, the
> - * remaining names will be silently ignored.
> + * Provides the list of names of active storage pools upto maxnames.

s/upto/up to/

> + * If there are more than maxnames, the remaining names will be silently
> + * ignored.
> + *
> + * For more control over the results, see virConnectListAllStoragePools().
>   *
>   * Returns 0 on success, -1 on error

This lists the cross-reference, but not the fact that there is an
inherent race.  Based on the prior example, this should be something like:

Returns the number of pools found or -1 in case of error.  Note that
this command is inherently racy; a pool can be started between a call to
virConnectNumOfStoragePools() and this call; you are only guaranteed
that all currently active pools were listed if the return is less than
@maxnames.

> +++ b/src/libvirt_public.syms
> @@ -544,4 +544,9 @@ LIBVIRT_0.9.13 {
>          virDomainSnapshotRef;
>  } LIBVIRT_0.9.11;
>  
> +LIBVIRT_0.9.14 {
> +    global:
> +        virConnectListAllStoragePools;
> +} LIBVIRT_0.9.13;

Merge conflict with Guido's patch a91067f.  Should be easy to resolve.

-- 
Eric Blake   eblake at redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 620 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20120720/77f6034a/attachment-0001.sig>