[libvirt] [PATCH 3/3] lib: domain: Emphasise that users should wait for block job READY state via events

The transition to the ready state is best observed by events as it's ansynchronous and does not hint users to do polling. As currently only the qemu driver supports block copy and block commit and the ready state event was introduced by qemu 1.3 we can fully switch to the new approach. Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- src/libvirt-domain.c | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 92a095f00b..408a442abc 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -10291,8 +10291,10 @@ virDomainBlockRebase(virDomainPtr dom, const char *disk, * source file; progress in this phase can be tracked via the * virDomainBlockJobInfo() command, with a job type of * VIR_DOMAIN_BLOCK_JOB_TYPE_COPY. The job transitions to the second - * phase when the job info states cur == end, and remains alive to mirror - * all further changes to both source and destination. The user must + * phase when the block job event with state VIR_DOMAIN_BLOCK_JOB_READY is + * emitted for the given device. This information is also it's visible in the + * live XML as 'ready="yes"' attribute of the corresponding <mirror> element. + * All further changes are saved to both source and destination. The user must * call virDomainBlockJobAbort() to end the mirroring while choosing * whether to revert to source or pivot to the destination. An event is * issued when the job ends, and depending on the hypervisor, an event may @@ -10406,9 +10408,9 @@ virDomainBlockCopy(virDomainPtr dom, const char *disk, * of VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT, and operates in two phases. * In the first phase, the contents are being committed into @base, and the * job can only be canceled. The job transitions to the second phase when - * the job info states cur == end, and remains alive to keep all further - * changes to @top synchronized into @base; an event with status - * VIR_DOMAIN_BLOCK_JOB_READY is also issued to mark the job transition. + * the block job event with state VIR_DOMAIN_BLOCK_JOB_READY is + * emitted for the given device. This information is also it's visible in the + * live XML as 'ready="yes"' attribute of the corresponding <mirror> element. * Once in the second phase, the user must choose whether to cancel the job * (keeping @top as the active image, but now containing only the changes * since the time the job ended) or to pivot the job (adjusting to @base as -- 2.20.1