[libvirt] [PATCH v2 3/5] Introduce virDomainSuspendForDuration API

[Eric Blake]

On 01/26/2012 12:59 PM, Michal Privoznik wrote:
> This API allows a domain to be put into one of S# ACPI states.
> Currently, S3 and S4 are supported. These states are shared
> with virNodeSuspendForDuration.
> However, for now we don't support any duration other than zero.
> The same apply for flags.

I'm not reviewing 1, 2, or 4(as Dan said, there's still some churn on
the qemu side), but I can review this one and 5 for accuracy, assuming
you make the agreed name changes.

>  /**
> + * virDomainSuspendForDuration:
> + * @dom: a domain object
> + * @target: an OR'ed set of virNodeSuspendTarget

This is _not_ an OR'd set, but a linear list.  I'd say:

@target: a value from virNodeSuspendTarget

> + * @duration: currently unused, pass 0

I'd still document this for its intended purpose:

@duration: duration in seconds to suspend, or 0 for indefinite

as well as a disclaimer in the rest of the text stating that some
hypervisors require 0 for @duration.

> + * @flags: ditto

Rather than abbreviating with "ditto", I'd copy and paste one of the
other lines where we say things are unused, pass 0.

> + *
> + * Attempt to suspend given domain. However, more
> + * states are supported than in virDomainSuspend.

That didn't read well.  I'd say something like:

Attempt to have the guest enter the given @target power management
suspension level.  If @duration is non-zero, also schedule the guest to
resume normal operation after that many seconds, if nothing else has
resumed it earlier.  Some hypervisors require that @duration be 0, for
an indefinite suspension.

> +++ b/src/libvirt_public.syms
> @@ -520,6 +520,7 @@ LIBVIRT_0.9.10 {
>      global:
>          virDomainShutdownFlags;
>          virStorageVolWipePattern;
> +        virDomainSuspendForDuration;
>  } LIBVIRT_0.9.9;

Looks like you get to rebase on top of other API added today.

-- 
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/20120127/7a7da57b/attachment-0001.sig>