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