From: Peter Krempa <pkrempa@redhat.com>
Date: Fri, 4 Dec 2020 15:07:56 +0000 (+0100)
Subject: virDomainGetBlockJobInfo: Discourage polling for block job completion detection
X-Git-Tag: v7.0.0-rc1~296
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a015b5c0a12722db96c75143db01289b7ba344c1;p=thirdparty%2Flibvirt.git

virDomainGetBlockJobInfo: Discourage polling for block job completion detection

Add a note saying that polling virDomainGetBlockJobInfo is not a good
idea. Use events instead.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
---

diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index f5cd43ecea..5d3747fd39 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -9947,6 +9947,11 @@ virDomainBlockJobAbort(virDomainPtr dom, const char *disk,
  * and was no-op. In this case libvirt reports cur = 1 and end = 1.
  * Since 2.3.0.
  *
+ * Applications looking for a reliable and low-overhead way to determine whether
+ * a block job already finished or reached synchronised phase should register a
+ * handler for the VIR_DOMAIN_EVENT_ID_BLOCK_JOB_2 event instead of polling this
+ * API.
+ *
  * Note that the progress reported for blockjobs corresponding to a pull-mode
  * backup don't report progress of the backup but rather usage of temporary
  * space required for the backup.