[PATCH 1/7] virDomainGetBlockJobInfo: Discourage polling for block job completion detection

[Peter Krempa]

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

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 src/libvirt-domain.c | 5 +++++
 1 file changed, 5 insertions(+)

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.
-- 
2.28.0