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

[Daniel P. Berrange]

On Thu, Jul 21, 2011 at 03:52:52PM -0600, Eric Blake wrote:
> 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?

Not really...

> 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.

I don't think that analogy really works in virt to be honest.

> >+ *
> >+ * 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'm rather loathe to put a timeout parameter in, since that's
getting into the realm of policies and this turns into a can
of worms. How do you cancel the timeout... Is the timeout
preserved if the VM is migrated elsewhere instead ... What
if you want todo some ping check of the guest after the timeout
occurrs, but before killing...etc.etc.


Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|