On 11/15/2017 04:54 PM, Kashyap Chamarthy wrote: > On Wed, Nov 15, 2017 at 02:15:57PM -0500, John Snow wrote: >> >> >> On 11/15/2017 04:09 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. (Thanks: Max Reitz for reminding >>> me of this on IRC.) >>> >> >> I suppose this difference probably isn't covered in what was the >> bitmaps.md doc file (we don't bother covering mirror there, only >> backup); > > Your supposition is correct: Looking at the now-renamed > 'bitmaps.rst'[1], it isn't covered there. >
Makes sense, I don't think we need to correct this, and >> is it covered sufficiently in live-block-operations.rst ? > > I looked in there[2] too. Short answer: no. Long: In the "Live disk > synchronization — drive-mirror and blockdev-mirror" section, I simply > seemed to declare: > > "Issuing the command ``block-job-cancel`` after it emits the event > ``BLOCK_JOB_CANCELLED``" > > As if that's the *only* event it emits, which is clearly not the case. > So while at it, wonder if should I also update it > ('live-block-operations.rst') too. > It's an interesting gotcha that I wasn't really acutely aware of myself, so having it in the doc format for API programmers who aren't necessarily digging through our source sounds like a pleasant courtesy. > [1] https://git.qemu.org/?p=qemu.git;a=blob;f=docs/interop/bitmaps.rst > [2] > https://git.qemu.org/?p=qemu.git;a=blob;f=docs/interop/live-block-operations.rst#l513 > > Thanks Kashyap :)