[libvirt] [PATCH] virDomainShutdown*: Describe blocking behaviour
The description to both virDomainShutdown() and
virDomainShutdownFlags() is quite misleading when it comes to
blocking behaviour of these two APIs. Firstly, we support many
shutdown methods, from signalizing an ACPI event, through sending
a signal to guest agent assisted shutdown. Some of these methods
make the API return immediately, while others block the API until
domain is actually shut of. And since virDomainShutdown() is
equivalent to calling virDomainShutdownFlags(0), it's up to each
driver which methods to try. So the bare virDomainShutdown() may
block or may return immediately at the same time. I know, it's
confusing, but at least let users know.
Signed-off-by: Michal Privoznik <mprivozn(a)redhat.com>
---
src/libvirt-domain.c | 13 +++++++++----
1 file changed, 9 insertions(+), 4 deletions(-)
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index f1608dc..03b342f 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -1474,9 +1474,12 @@ virDomainScreenshot(virDomainPtr domain,
* 'on_poweroff' XML setting resulting in a domain that reboots instead of
* shutting down. For guests that react to a shutdown request, the differences
* from virDomainDestroy() are that the guests disk storage will be in a
- * stable state rather than having the (virtual) power cord pulled, and
- * this command returns as soon as the shutdown request is issued rather
- * than blocking until the guest is no longer running.
+ * stable state rather than having the (virtual) power cord pulled. It's up to
+ * hypervisor's driver implementation what methods of
+ * virDomainShutdownFlagValues are tried and in which order. As described in
+ * virDomainShutdownFlags, this call may return immediately after the shutdown
+ * request is send, or it may block indefinitely long, until the domain is
+ * actually shut off.
*
* If the domain is transient and has any snapshot metadata (see
* virDomainSnapshotNum()), then that metadata will automatically
@@ -1540,7 +1543,9 @@ virDomainShutdown(virDomainPtr domain)
* and a hypervisor is not required to support all methods.
*
* To use guest agent (VIR_DOMAIN_SHUTDOWN_GUEST_AGENT) the domain XML
- * must have <channel> configured.
+ * must have <channel> configured. Moreover, depending on underlying
+ * hypervisor used, passing this flag may block the API until the domain
+ * is shut off (which is not guaranteed to happen anyway).
*
* Returns 0 in case of success and -1 in case of failure.
*/
--
2.0.5