[libvirt] [PATCH 01/12] shutdown: Define new public API virDomainShutdownFlags

[Eric Blake]

On 07/21/2011 02:53 PM, Michal Privoznik wrote:
> This introduces new API virDomainShutdownFlags to allow
> domain destroying with flags, as the existing API virDomainShutdown
> misses flags.
>
> The set of flags is defined in virDomainShutdownFlagsValues enum,
> which is currently commented, because it is empty.
>
> Calling this API with no flags set (@flags == 0) is equivalent calling
> virDomainShutdown.
> ---
>   include/libvirt/libvirt.h.in |    6 ++++
>   src/driver.h                 |    4 +++
>   src/libvirt.c                |   54 ++++++++++++++++++++++++++++++++++++++++++
>   src/libvirt_public.syms      |    1 +
>   4 files changed, 65 insertions(+), 0 deletions(-)

>
>   /**
> + * virDomainShutdownFlags:
> + * @domain: a domain object
> + * @flags: an OR'ed set of virDomainShutdownFlagsValues
> + *
> + * Shutdown a domain, the domain object is still usable there after but
> + * the domain OS is being stopped. Note that the guest OS may ignore the
> + * request.
> + *
> + * TODO: should we add an option for reboot, knowing it may not be doable
> + *       in the general case ?

Do we really want this TODO to show up in the web page?

And this same question could be asked of virDomainDestroyFlags, since it 
is conceivable to have hardware where the BIOS is set to auto-power-on 
after a power-loss event; virDomainDestroy corresponds to the power 
loss, and the auto-restart flag corresponds to the BIOS wakeup event.

> + *
> + * Calling this function with no @flags set (equal to zero)
> + * is equivalent to calling virDomainShutdown.
> + *
> + * Returns 0 in case of success and -1 in case of failure.
> + */
> +int
> +virDomainShutdownFlags(virDomainPtr domain,
> +                       unsigned int flags)

Is this flexible enough?  Since shutdown requires guest cooperation, I 
wonder if we should instead provide this signature:

virDomainShutdownFlags(virDomainPtr domain, unsigned int timeout, 
unsigned int flags)

If @timeout is 0, nothing further is done after requesting the guest 
shutdown.  If @timeout is non-zero, then if that many seconds elapse and 
the guest is still running, then the hypervisor will forcefully stop the 
guest as if by virDomainDestroyFlags, using the same set of flags passed 
to this function.  In all cases, this command returns immediately after 
making the shutdown request; you must register for domain lifecycle 
events or poll for domain status to see if the domain has actually shut 
down yet.

Or possibly:

If @timeout is 0, nothing further is done after requesting the guest 
shutdown.  If @timeout is non-zero, then if that many seconds elapse and 
the guest is still running, then the hypervisor will forcefully stop the 
guest as if by virDomainDestroyFlags, using the same set of flags passed 
to this function except VIR_DOMAIN_SHUTDOWN_BLOCK.  In all cases, if 
@flags includes VIR_DOMAIN_SHUTDOWN_BLOCK, this command blocks until the 
guest halts or the timeout expires or virDomainShutdownAbort() is called 
by another thread; without that flag, this call returns immediately 
after making the shutdown request and you must register for domain 
lifecycle events or poll for domain status to see if the domain has 
actually shut down yet.

I know I said earlier that it would be nice to provide 
virDomainShutdownFlags as a parallel to virDestroyFlags, so we aren't 
locked into a flag-less API, but now that I think about it more, I'm 
worried that we might still be locking ourselves into something too 
inflexible.

-- 
Eric Blake   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org