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.