From: Peter Krempa <pkrempa@redhat.com>
Date: Thu, 6 Jun 2024 16:04:57 +0000 (+0200)
Subject: qemuDomainObjWait: Add documentation
X-Git-Tag: v10.5.0-rc1~38
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=da8d97e4e24aefbb20b6ea168fa65f429a428364;p=thirdparty%2Flibvirt.git

qemuDomainObjWait: Add documentation

Document why this function exists and meaning of return values.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
---

diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c
index 9bbad887e0..4eba4e91c5 100644
--- a/src/qemu/qemu_domain.c
+++ b/src/qemu/qemu_domain.c
@@ -12368,6 +12368,18 @@ qemuDomainRemoveLogs(virQEMUDriver *driver,
 }
 
 
+/**
+ * qemuDomainObjWait:
+ * @vm: domain object
+ *
+ * Wait for a signal on the main domain condition. Take into account internal
+ * qemu state in addition to what virDomainObjWait checks. Code in the qemu
+ * driver must use this function exclusively instead of virDomainObjWait.
+ *
+ * Returns:
+ *  0 on successful wait AND VM is guaranteed to be running
+ *  -1 on failure to wait or VM was terminated while waiting
+ */
 int
 qemuDomainObjWait(virDomainObj *vm)
 {