On 06/05/2012 07:19 AM, Peter Krempa wrote:
> This patch adds a new public api that lists domains. The new approach is
> different from those used before. There are key points to this:
>
> 1) The list is acquired atomically and contains both active and inactive
> domains (guests). This eliminates the need to call two different list
> APIs, where the state might change in between of the calls.
s/between of/between/
>
> 2) The returned list consists of virDomainPtrs instead of names or ID's
> that have to be converted to virDomainPtrs anyways using separate calls
> for each one of them. This is more convenient and saves hypervisor calls.
>
> 3) The returned list is auto-allocated. This saves a lot hassle for the
s/lot/lot of/
> users.
>
> 4) Built in support for filtering. The API call supports various
> filtering flags that modify the output list according to user needs.
>
> Available filter groups:
> Domain status:
> VIR_CONNECT_LIST_DOMAINS_ACTIVE, VIR_CONNECT_LIST_DOMAINS_INACTIVE
>
> Domain persistence:
> VIR_CONNECT_LIST_DOMAINS_PERSISTENT,
> VIR_CONNECT_LIST_DOMAINS_TRANSIENT
>
> Domain state:
> VIR_CONNECT_LIST_DOMAINS_RUNNING, VIR_CONNECT_LIST_DOMAINS_PAUSED,
> VIR_CONNECT_LIST_DOMAINS_SHUTOFF, VIR_CONNECT_LIST_DOMAINS_OTHER
>
> Presense of managed save image:
s/Presense/Presence/
> VIR_CONNECT_LIST_DOMAINS_MANAGEDSAVE,
> VIR_CONNECT_LIST_DOMAINS_NO_MANAGEDSAVE
>
> Auto-start option:
> VIR_CONNECT_LIST_DOMAINS_AUTOSTART,
> VIR_CONNECT_LIST_DOMAINS_NO_AUTOSTART
>
> Presense of snapshot:
s/Presense/Presence/
> VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT,
> VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT
>
> 5) The python binding returns a list of domain objects that is very neat
> to work with.
>
> The only problem with this approach is no support from code generators
> so both RPC code and python bindings had to be written manualy.
s/manualy/manually/
>
> *include/libvirt/libvirt.h.in: - add API prototype
> - clean up whitespace mistakes nearby
> *python/generator.py: - inhibit generation of the bindings for the new
> api
> *src/driver.h: - add driver prototype
> - clean up some whitespace mistakes nearby
> *src/libvirt.c: - add public implementation
> *src/libvirt_public.syms: - export the new symbol
> ---
> Diff to v1:
> - added docs and filtering flags
> ---
> include/libvirt/libvirt.h.in | 36 ++++++++++++-
> python/generator.py | 1 +
> src/driver.h | 11 +++-
> src/libvirt.c | 122 +++++++++++++++++++++++++++++++++++++++++-
> src/libvirt_public.syms | 5 ++
> 5 files changed, 168 insertions(+), 7 deletions(-)
> @@ -866,6 +870,7 @@ struct _virDriver {
> virDrvGetCapabilities getCapabilities;
> virDrvListDomains listDomains;
> virDrvNumOfDomains numOfDomains;
> + virDrvListAllDomains listAllDomains;
Spacing looks inconsistent here. (Hmm, changing things to use space
instead of tab would be a separate commit.)
>
> /**
> + * virConnectListAllDomains:
> + * @conn: Pointer to the hypervisor connection.
> + * @domains: Pointer to a variable to store the array containing domain objects
> + * or NULL if the list is not required (just returns number of guests).
> + * @flags: bitwise-OR of virConnectListAllDomainsFlags
> + *
> + * Collect a possibly-filtered list of all domains, and return an allocated
> + * array of information for each. This API solves the race inherent in
> + * virConnectListDomains() and virConnectListDefinedDomains().
> + *
> + * Normally, all domains are returned; however, @flags can be used to
> + * filter the results for a smaller list of targetted domains. The valid
s/targetted/targeted/
> + *
> + * Returns the number of domains found or -1 in case of error. On success,
> + * the array stored into @doms is guaranteed to have an extra allocated
> + * element set to NULL, to make iteration easier.
Maybe:
s/an extra allocated element set to NULL/& but not included in the
return count/
to make it obvious that the trailing NULL does not impact the return value.
> + *
> + * Example of usage:
> + * virDomainPtr *domains;
> + * virDomainPtr dom;
> + * int i;
> + *
I'd drop this blank line.
> + * int ret;
> + * unsigned int flags = VIR_CONNECT_LIST_RUNNING |
> + * VIR_CONNECT_LIST_PERSISTENT;
> + *
> + * ret = virConnectListAllDomains(conn, &domains, flags);
> + * if (ret < 0)
> + * error();
> + *
> + * for (i = 0; i < ret; i++) {
> + * do_someting_with_domain(domains[i]);
s/someting/something/
> +{
> + VIR_DEBUG("conn=%p, domains=%p, flags=%x", conn, domains, flags);
> +
> + virResetLastError();
> +
> + if (!VIR_IS_CONNECT(conn)) {
> + virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
> + virDispatchError(NULL);
> + return -1;
> + }
There's now a conflict between your commit and danpb's cleanups to error
reporting in libvirt.c - whoever commits second should make sure to
rebase properly.
ACK with doc tweaks included.
--
Eric Blake eblake@xxxxxxxxxx +1-919-301-3266
Libvirt virtualization library http://libvirt.org
Attachment:
signature.asc
Description: OpenPGP digital signature
-- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list