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 f5cd43ecea3184e9a20eb052782c703ca93ee014..5d3747fd398804f57d9fb43e3697405d9b66c8f4 100644 (file)
--- 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.