[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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



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 redhat com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]