From c117bb14ff633848cc6b0ff77f081f583dfa8c5e Mon Sep 17 00:00:00 2001 From: Kashyap Chamarthy Date: Tue, 21 Nov 2017 12:52:53 +0100 Subject: QAPI & interop: Clarify events emitted by 'block-job-cancel' When you cancel an in-progress 'mirror' job (or "active `block-commit`") with QMP `block-job-cancel`, it emits the event: BLOCK_JOB_CANCELLED. However, when `block-job-cancel` is issued *after* `drive-mirror` has indicated (via the event BLOCK_JOB_READY) that the source and destination have reached synchronization: [...] # Snip `drive-mirror` invocation & outputs { "execute":"block-job-cancel", "arguments":{ "device":"virtio0" } } {"return": {}} It (`block-job-cancel`) will counterintuitively emit the event 'BLOCK_JOB_COMPLETED': { "timestamp":{ "seconds":1510678024, "microseconds":526240 }, "event":"BLOCK_JOB_COMPLETED", "data":{ "device":"virtio0", "len":41126400, "offset":41126400, "speed":0, "type":"mirror" } } But this is expected behaviour, where the _COMPLETED event indicates that synchronization has successfully ended (and the destination now 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.) Signed-off-by: Kashyap Chamarthy Reviewed-by: Eric Blake Signed-off-by: Kevin Wolf --- qapi/block-core.json | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'qapi/block-core.json') diff --git a/qapi/block-core.json b/qapi/block-core.json index 76bf50f813..dd763dcf87 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -2065,6 +2065,12 @@ # BLOCK_JOB_CANCELLED event. Before that happens the job is still visible when # enumerated using query-block-jobs. # +# 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. +# # For streaming, the image file retains its backing file unless the streaming # operation happens to complete just as it is being cancelled. A new streaming # operation can be started at a later time to finish copying all data from the -- cgit v1.2.3-55-g7522