Re: [PATCH v2 1/2] qapi: synchronize jobs and block-jobs documentation
On Fri, Apr 04, 2025 at 10:31:53PM +0300, Vladimir Sementsov-Ogievskiy wrote:
Actualize documentation and synchronize it for commands which
actually
call the same functions internally.
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov(a)yandex-team.ru>
---
qapi/block-core.json | 59 +++++++++++++++++++++++++-------------------
qapi/job.json | 29 ++++++++++++++++++++--
2 files changed, 61 insertions(+), 27 deletions(-)
Overall makes sense, but one thing jumped out at me:
# @block-job-complete:
#
-# Manually trigger completion of an active background block operation.
-# This is supported for drive mirroring, where it also switches the
-# device to write to the target path only. The ability to complete is
-# signaled with a BLOCK_JOB_READY event.
+# Manually trigger completion of an active job in the READY or STANDBY
+# state. Completing the job in any other state is an error.
+#
+# This is supported only for drive mirroring (which includes
+# drive-mirror, blockdev-mirror and block-commit job (only in case of
+# "active commit", when the node being commited is used by the guest)),
+# where it also switches the device to write to the target path only.
The doubly-nested parenthetical feels long. Is there a more concise
way of expressing the list of three commands, where one of the
commands only supports it in the special case of "active commit"?
--
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization: qemu.org | libguestfs.org