qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Qemu-devel] [PATCH v3 for-2.11] QAPI & interop: Clarify events emit


From: Eric Blake
Subject: Re: [Qemu-devel] [PATCH v3 for-2.11] QAPI & interop: Clarify events emitted by 'block-job-cancel'
Date: Fri, 17 Nov 2017 11:07:41 -0600
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.4.0

On 11/17/2017 10:25 AM, Kashyap Chamarthy wrote:
> When you cancel an in-progress live block operation with QMP
> `block-job-cancel`, it emits the event: BLOCK_JOB_CANCELLED.  However,
> when `block-job-cancel` is issued after `drive-mirror` has indicated (by
> emitting the event BLOCK_JOB_READY) that the source and destination
> remain synchronized:
> 

> But this is expected behaviour, where the _COMPLETED event indicates
> that synchronization has successfully ended (and the destination has a
> point-in-time copy, which is at the time of cancel).
> 
> So add a small note to this effect in 'block-core.json'.  While at it,
> also update the "Live disk synchronization -- drive-mirror and
> blockdev-mirror" section in 'live-block-operations.rst'.
> 
> (Thanks: Max Reitz for reminding me of this caveat on IRC.)

Sorry for not wordsmithing on earlier versions:

> 
> Signed-off-by: Kashyap Chamarthy <address@hidden>
> ---

> +.. note::
> +
> +    When you cancel an in-progress 'mirror' job *before* the source and
> +    target are synchronized, ``block-job-cancel`` will emit the event
> +    ``BLOCK_JOB_CANCELLED``.  However, note that if you cancel a
> +    'mirror' job *after* it has indicated (by emitting the event
> +    ``BLOCK_JOB_READY``) that the source and target now remain
> +    synchronized, then ``block-job-cancel`` will emit the event

Might read slightly nicer as:

the source and target have reached synchronization,


> +++ b/qapi/block-core.json
> @@ -2065,6 +2065,14 @@
>  # BLOCK_JOB_CANCELLED event.  Before that happens the job is still visible 
> when
>  # enumerated using query-block-jobs.
>  #
> +# Note that the 'block-job-cancel' command will emit the event
> +# BLOCK_JOB_COMPLETED if you issue it ('block-job-cancel') after 
> 'drive-mirror'
> +# has indicated (by emitting the event BLOCK_JOB_READY) that the source and
> +# destination remain synchronized.  In this case, the BLOCK_JOB_COMPLETED
> +# event indicates that synchronization (from 'drive-mirror') has successfully
> +# ended and the destination now has a point-in-time copy, which is at the 
> time
> +# of cancel.


Accurate, but a bit hard to follow the flow of the sentence.  Might read
nicer as:

Note that if you issue 'block-job-cancel' after 'drive-mirror' has
indicated (via the event BLOCK_JOB_READY) that the source and
destination are synchronized, then the event triggered by this command
changes to BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended
and the destination now has a point-in-time copy tied to the time of the
cancellation.

Documentation is worth of inclusion in 2.11.  Whether you keep your
wording, or incorporate mine in a v4, you can add:
Reviewed-by: Eric Blake <address@hidden>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Attachment: signature.asc
Description: OpenPGP digital signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]