motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-08 02:03:56 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

qapi: Improve documentation around job state @concluded

Browse source 
We use "the query list" in a few places.  It's not entirely obvious
what that means.  It's actually the output of query-jobs or
query-block-jobs.

Documentation of @auto-dismiss talks about the job disappearing from
the query list when it reaches state @concluded.  This is less than
precise.  The job doesn't merely disappear from the query list, it
disappears, period.

Documentation of JobStatus @concluded explains "the job will remain in
the query list until it is dismissed".  Again less than precise.  It
remains in state @concluded until dismissed.

Rephrase without use of "the query list" for clarity and precision.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-14-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
This commit is contained in:
Markus Armbruster 2025-05-27 09:39:16 +02:00
parent feeb08c260
commit 8fa2020647
2 changed files with 8 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

19
qapi/block-core.json
View file

@ -1417,8 +1417,8 @@
# @auto-finalize: Job will finalize itself when PENDING, moving to the # @auto-finalize: Job will finalize itself when PENDING, moving to the
# CONCLUDED state. (since 2.12) # CONCLUDED state. (since 2.12)
# #
# @auto-dismiss: Job will dismiss itself when CONCLUDED, moving to the # @auto-dismiss: Job will dismiss itself when CONCLUDED, and
# NULL state and disappearing from the query list. (since 2.12) # disappear. (since 2.12)
# #
# @error: Error information if the job did not complete successfully. # @error: Error information if the job did not complete successfully.
# Not set if the job completed successfully. (since 2.12.1) # Not set if the job completed successfully. (since 2.12.1)
@ -1614,8 +1614,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state # @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits # after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear # @job-dismiss. When true, this job will automatically disappear
# from the query list without user intervention. Defaults to # without user intervention. Defaults to true. (Since 2.12)
# true. (Since 2.12)
# #
# @filter-node-name: the node name that should be assigned to the # @filter-node-name: the node name that should be assigned to the
# filter driver that the backup job inserts into the graph above # filter driver that the backup job inserts into the graph above
@ -1855,8 +1854,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state # @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits # after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear # @job-dismiss. When true, this job will automatically disappear
# from the query list without user intervention. Defaults to # without user intervention. Defaults to true. (Since 3.1)
# true. (Since 3.1)
# #
# Features: # Features:
# #
@ -2219,8 +2217,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state # @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits # after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear # @job-dismiss. When true, this job will automatically disappear
# from the query list without user intervention. Defaults to # without user intervention. Defaults to true. (Since 3.1)
# true. (Since 3.1)
# #
# Since: 1.3 # Since: 1.3
## ##
@ -2538,8 +2535,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state # @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits # after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear # @job-dismiss. When true, this job will automatically disappear
# from the query list without user intervention. Defaults to # without user intervention. Defaults to true. (Since 3.1)
# true. (Since 3.1)
# #
# @target-is-zero: Assume the destination reads as all zeroes before # @target-is-zero: Assume the destination reads as all zeroes before
# the mirror started. Setting this to true can speed up the # the mirror started. Setting this to true can speed up the
@ -2866,8 +2862,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state # @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits # after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear # @job-dismiss. When true, this job will automatically disappear
# from the query list without user intervention. Defaults to # without user intervention. Defaults to true. (Since 3.1)
# true. (Since 3.1)
# #
# Errors: # Errors:
# - If @device does not exist, DeviceNotFound. # - If @device does not exist, DeviceNotFound.

2
qapi/job.json
View file

@ -74,7 +74,7 @@
# process. # process.
# #
# @concluded: The job has finished all work. If auto-dismiss was set # @concluded: The job has finished all work. If auto-dismiss was set
# to false, the job will remain in the query list until it is # to false, the job will remain in this state until it is
# dismissed via @job-dismiss. # dismissed via @job-dismiss.
# #
# @null: The job is in the process of being dismantled. This state # @null: The job is in the process of being dismantled. This state