# -*- Mode: Python -*-
+# vim: filetype=python
##
-# == Background jobs
+# = Background jobs
##
##
#
# @create: image creation job type, see "blockdev-create" (since 3.0)
#
+# @amend: image options amend job type, see "x-blockdev-amend" (since
+# 5.1)
+#
+# @snapshot-load: snapshot load job type, see "snapshot-load" (since
+# 6.0)
+#
+# @snapshot-save: snapshot save job type, see "snapshot-save" (since
+# 6.0)
+#
+# @snapshot-delete: snapshot delete job type, see "snapshot-delete"
+# (since 6.0)
+#
# Since: 1.7
##
{ 'enum': 'JobType',
- 'data': ['commit', 'stream', 'mirror', 'backup', 'create'] }
+ 'data': ['commit', 'stream', 'mirror', 'backup', 'create', 'amend',
+ 'snapshot-load', 'snapshot-save', 'snapshot-delete'] }
##
# @JobStatus:
#
# Indicates the present state of a given job in its lifetime.
#
-# @undefined: Erroneous, default state. Should not ever be visible.
+# @undefined: Erroneous, default state. Should not ever be visible.
#
# @created: The job has been created, but not yet started.
#
# @running: The job is currently running.
#
-# @paused: The job is running, but paused. The pause may be requested by
-# either the QMP user or by internal processes.
+# @paused: The job is running, but paused. The pause may be requested
+# by either the QMP user or by internal processes.
#
-# @ready: The job is running, but is ready for the user to signal completion.
-# This is used for long-running jobs like mirror that are designed to
-# run indefinitely.
+# @ready: The job is running, but is ready for the user to signal
+# completion. This is used for long-running jobs like mirror that
+# are designed to run indefinitely.
#
-# @standby: The job is ready, but paused. This is nearly identical to @paused.
-# The job may return to @ready or otherwise be canceled.
+# @standby: The job is ready, but paused. This is nearly identical to
+# @paused. The job may return to @ready or otherwise be canceled.
#
-# @waiting: The job is waiting for other jobs in the transaction to converge
-# to the waiting state. This status will likely not be visible for
-# the last job in a transaction.
+# @waiting: The job is waiting for other jobs in the transaction to
+# converge to the waiting state. This status will likely not be
+# visible for the last job in a transaction.
#
-# @pending: The job has finished its work, but has finalization steps that it
-# needs to make prior to completing. These changes will require
-# manual intervention via @job-finalize if auto-finalize was set to
-# false. These pending changes may still fail.
+# @pending: The job has finished its work, but has finalization steps
+# that it needs to make prior to completing. These changes will
+# require manual intervention via @job-finalize if auto-finalize
+# was set to false. These pending changes may still fail.
#
-# @aborting: The job is in the process of being aborted, and will finish with
-# an error. The job will afterwards report that it is @concluded.
-# This status may not be visible to the management process.
+# @aborting: The job is in the process of being aborted, and will
+# finish with an error. The job will afterwards report that it is
+# @concluded. This status may not be visible to the management
+# process.
#
-# @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 dismissed via
-# @job-dismiss.
+# @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
+# dismissed via @job-dismiss.
#
-# @null: The job is in the process of being dismantled. This state should not
-# ever be visible externally.
+# @null: The job is in the process of being dismantled. This state
+# should not ever be visible externally.
#
# Since: 2.12
##
#
# @finalize: see @job-finalize
#
+# @change: see @block-job-change (since 8.2)
+#
# Since: 2.12
##
{ 'enum': 'JobVerb',
'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
- 'finalize' ] }
+ 'finalize', 'change' ] }
##
# @JOB_STATUS_CHANGE:
# Emitted when a job transitions to a different status.
#
# @id: The job identifier
+#
# @status: The new job status
#
-# Since: 2.13
+# Since: 3.0
##
{ 'event': 'JOB_STATUS_CHANGE',
'data': { 'id': 'str',
#
# Pause an active job.
#
-# This command returns immediately after marking the active job for pausing.
-# Pausing an already paused job is an error.
+# This command returns immediately after marking the active job for
+# pausing. Pausing an already paused job is an error.
#
-# The job will pause as soon as possible, which means transitioning into the
-# PAUSED state if it was RUNNING, or into STANDBY if it was READY. The
-# corresponding JOB_STATUS_CHANGE event will be emitted.
+# The job will pause as soon as possible, which means transitioning
+# into the PAUSED state if it was RUNNING, or into STANDBY if it was
+# READY. The corresponding JOB_STATUS_CHANGE event will be emitted.
#
# Cancelling a paused job automatically resumes it.
#
# @id: The job identifier.
#
-# Since: 2.13
+# Since: 3.0
##
{ 'command': 'job-pause', 'data': { 'id': 'str' } }
#
# Resume a paused job.
#
-# This command returns immediately after resuming a paused job. Resuming an
-# already running job is an error.
+# This command returns immediately after resuming a paused job.
+# Resuming an already running job is an error.
#
-# @id : The job identifier.
+# @id: The job identifier.
#
-# Since: 2.13
+# Since: 3.0
##
{ 'command': 'job-resume', 'data': { 'id': 'str' } }
# This command returns immediately after marking the active job for
# cancellation.
#
-# The job will cancel as soon as possible and then emit a JOB_STATUS_CHANGE
-# event. Usually, the status will change to ABORTING, but it is possible that
-# a job successfully completes (e.g. because it was almost done and there was
-# no opportunity to cancel earlier than completing the job) and transitions to
-# PENDING instead.
+# The job will cancel as soon as possible and then emit a
+# JOB_STATUS_CHANGE event. Usually, the status will change to
+# ABORTING, but it is possible that a job successfully completes (e.g.
+# because it was almost done and there was no opportunity to cancel
+# earlier than completing the job) and transitions to PENDING instead.
#
# @id: The job identifier.
#
-# Since: 2.13
+# Since: 3.0
##
{ 'command': 'job-cancel', 'data': { 'id': 'str' } }
-
##
# @job-complete:
#
#
# @id: The job identifier.
#
-# Since: 2.13
+# Since: 3.0
##
{ 'command': 'job-complete', 'data': { 'id': 'str' } }
##
# @job-dismiss:
#
-# Deletes a job that is in the CONCLUDED state. This command only needs to be
-# run explicitly for jobs that don't have automatic dismiss enabled.
+# Deletes a job that is in the CONCLUDED state. This command only
+# needs to be run explicitly for jobs that don't have automatic
+# dismiss enabled.
#
-# This command will refuse to operate on any job that has not yet reached its
-# terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of JOB_READY
-# event, job-cancel or job-complete will still need to be used as appropriate.
+# This command will refuse to operate on any job that has not yet
+# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that make
+# use of JOB_READY event, job-cancel or job-complete will still need
+# to be used as appropriate.
#
# @id: The job identifier.
#
-# Since: 2.13
+# Since: 3.0
##
{ 'command': 'job-dismiss', 'data': { 'id': 'str' } }
##
# @job-finalize:
#
-# Instructs all jobs in a transaction (or a single job if it is not part of any
-# transaction) to finalize any graph changes and do any necessary cleanup. This
-# command requires that all involved jobs are in the PENDING state.
+# Instructs all jobs in a transaction (or a single job if it is not
+# part of any transaction) to finalize any graph changes and do any
+# necessary cleanup. This command requires that all involved jobs are
+# in the PENDING state.
#
-# For jobs in a transaction, instructing one job to finalize will force
-# ALL jobs in the transaction to finalize, so it is only necessary to instruct
-# a single member job to finalize.
+# For jobs in a transaction, instructing one job to finalize will
+# force ALL jobs in the transaction to finalize, so it is only
+# necessary to instruct a single member job to finalize.
#
-# @id: The identifier of any job in the transaction, or of a job that is not
-# part of any transaction.
+# @id: The identifier of any job in the transaction, or of a job that
+# is not part of any transaction.
#
-# Since: 2.13
+# Since: 3.0
##
{ 'command': 'job-finalize', 'data': { 'id': 'str' } }
#
# Information about a job.
#
-# @id: The job identifier
+# @id: The job identifier
#
-# @type: The kind of job that is being performed
+# @type: The kind of job that is being performed
#
-# @status: Current job state/status
+# @status: Current job state/status
#
-# @current-progress: Progress made until now. The unit is arbitrary and the
-# value can only meaningfully be used for the ratio of
-# @current-progress to @total-progress. The value is
-# monotonically increasing.
+# @current-progress: Progress made until now. The unit is arbitrary
+# and the value can only meaningfully be used for the ratio of
+# @current-progress to @total-progress. The value is
+# monotonically increasing.
#
-# @total-progress: Estimated @current-progress value at the completion of
-# the job. This value can arbitrarily change while the
-# job is running, in both directions.
+# @total-progress: Estimated @current-progress value at the completion
+# of the job. This value can arbitrarily change while the job is
+# running, in both directions.
#
-# @error: If this field is present, the job failed; if it is
-# still missing in the CONCLUDED state, this indicates
-# successful completion.
+# @error: If this field is present, the job failed; if it is still
+# missing in the CONCLUDED state, this indicates successful
+# completion.
#
-# The value is a human-readable error message to describe
-# the reason for the job failure. It should not be parsed
-# by applications.
+# The value is a human-readable error message to describe the
+# reason for the job failure. It should not be parsed by
+# applications.
#
-# Since: 2.13
+# Since: 3.0
##
{ 'struct': 'JobInfo',
'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus',
#
# Returns: a list with a @JobInfo for each active job
#
-# Since: 2.13
+# Since: 3.0
##
{ 'command': 'query-jobs', 'returns': ['JobInfo'] }
projects / mirror_qemu.git / blobdiff