qapi/job.json - qemu - Git at Google

 # -*- Mode: Python -*-
 # vim: filetype=python

 ##
 # ***************
 # Background jobs
 # ***************
 ##

 ##
 # @JobType:
 #
 # Type of a background job.
 #
 # @commit: block commit job type, see `block-commit`
 #
 # @stream: block stream job type, see `block-stream`
 #
 # @mirror: drive mirror job type, see `drive-mirror`
 #
 # @backup: drive backup job type, see `drive-backup`
 #
 # @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', '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.
 #
 # @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.
 #
 # @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.
 #
 # @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.
 #
 # @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 this state 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.
 #
 # Since: 2.12
 ##
 { 'enum': 'JobStatus',
   'data': ['undefined', 'created', 'running', 'paused', 'ready', 'standby',
            'waiting', 'pending', 'aborting', 'concluded', 'null' ] }

 ##
 # @JobVerb:
 #
 # Represents command verbs that can be applied to a job.
 #
 # @cancel: see `job-cancel`
 #
 # @pause: see `job-pause`
 #
 # @resume: see `job-resume`
 #
 # @set-speed: see `block-job-set-speed`
 #
 # @complete: see `job-complete`
 #
 # @dismiss: see `job-dismiss`
 #
 # @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', 'change' ] }

 ##
 # @JOB_STATUS_CHANGE:
 #
 # Emitted when a job transitions to a different status.
 #
 # @id: The job identifier
 #
 # @status: The new job status
 #
 # Since: 3.0
 ##
 { 'event': 'JOB_STATUS_CHANGE',
   'data': { 'id': 'str',
             'status': 'JobStatus' } }

 ##
 # @job-pause:
 #
 # Pause an active job.
 #
 # 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.
 #
 # Cancelling a paused job automatically resumes it.
 #
 # @id: The job identifier.
 #
 # Since: 3.0
 ##
 { 'command': 'job-pause', 'data': { 'id': 'str' } }

 ##
 # @job-resume:
 #
 # Resume a paused job.
 #
 # This command returns immediately after resuming a paused job.
 # Resuming an already running job is an error.
 #
 # This command also clears the error status for block-jobs (stream,
 # commit, mirror, backup).
 #
 # @id: The job identifier.
 #
 # Since: 3.0
 ##
 { 'command': 'job-resume', 'data': { 'id': 'str' } }

 ##
 # @job-cancel:
 #
 # Instruct an active background job to cancel at the next opportunity.
 # 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.
 #
 # @id: The job identifier.
 #
 # Since: 3.0
 ##
 { 'command': 'job-cancel', 'data': { 'id': 'str' } }

 ##
 # @job-complete:
 #
 # 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, where it also switches
 # the device to write to the target path only.  Note that drive
 # mirroring 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).  The ability to complete is signaled with a
 # `BLOCK_JOB_READY` event.
 #
 # This command completes an active background block operation
 # synchronously.  The ordering of this command's return with the
 # `BLOCK_JOB_COMPLETED` event is not defined.  Note that if an I/O error
 # occurs during the processing of this command: 1) the command itself
 # will fail; 2) the error will be processed according to the
 # rerror/werror arguments that were specified when starting the
 # operation.
 #
 # @id: The job identifier.
 #
 # 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.  In turn, automatic dismiss may be enabled only
 # for jobs that have @auto-dismiss option, which are `drive-backup`,
 # `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and
 # `block-stream`.  @auto-dismiss is enabled by default for these
 # jobs.
 #
 # This command will refuse to operate on any job that has not yet
 # reached its terminal state, CONCLUDED.  For jobs that make use of
 # the JOB_READY event, `job-cancel` or `job-complete` will still need to
 # be used as appropriate.
 #
 # @id: The job identifier.
 #
 # 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.
 #
 # 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.
 #
 # The command is applicable only to jobs which have @auto-finalize option
 # and only when this option is set to false.
 #
 # @id: The identifier of any job in the transaction, or of a job that
 #     is not part of any transaction.
 #
 # Since: 3.0
 ##
 { 'command': 'job-finalize', 'data': { 'id': 'str' } }

 ##
 # @JobInfo:
 #
 # Information about a job.
 #
 # @id: The job identifier
 #
 # @type: The kind of job that is being performed
 #
 # @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.
 #
 # @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.
 #
 #     The value is a human-readable error message to describe the
 #     reason for the job failure.  It should not be parsed by
 #     applications.
 #
 # Since: 3.0
 ##
 { 'struct': 'JobInfo',
   'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus',
             'current-progress': 'int', 'total-progress': 'int',
             '*error': 'str' } }

 ##
 # @query-jobs:
 #
 # Return information about jobs.
 #
 # Returns: a list with info for each active job
 #
 # Since: 3.0
 ##
 { 'command': 'query-jobs', 'returns': ['JobInfo'] }
	# -- Mode: Python --
	# vim: filetype=python

	##
	# ***************
	# Background jobs
	# ***************
	##

	##
	# @JobType:
	#
	# Type of a background job.
	#
	# @commit: block commit job type, see `block-commit`
	#
	# @stream: block stream job type, see `block-stream`
	#
	# @mirror: drive mirror job type, see `drive-mirror`
	#
	# @backup: drive backup job type, see `drive-backup`
	#
	# @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', '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.
	#
	# @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.
	#
	# @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.
	#
	# @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.
	#
	# @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 this state 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.
	#
	# Since: 2.12
	##
	{ 'enum': 'JobStatus',
	'data': ['undefined', 'created', 'running', 'paused', 'ready', 'standby',
	'waiting', 'pending', 'aborting', 'concluded', 'null' ] }

	##
	# @JobVerb:
	#
	# Represents command verbs that can be applied to a job.
	#
	# @cancel: see `job-cancel`
	#
	# @pause: see `job-pause`
	#
	# @resume: see `job-resume`
	#
	# @set-speed: see `block-job-set-speed`
	#
	# @complete: see `job-complete`
	#
	# @dismiss: see `job-dismiss`
	#
	# @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', 'change' ] }

	##
	# @JOB_STATUS_CHANGE:
	#
	# Emitted when a job transitions to a different status.
	#
	# @id: The job identifier
	#
	# @status: The new job status
	#
	# Since: 3.0
	##
	{ 'event': 'JOB_STATUS_CHANGE',
	'data': { 'id': 'str',
	'status': 'JobStatus' } }

	##
	# @job-pause:
	#
	# Pause an active job.
	#
	# 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.
	#
	# Cancelling a paused job automatically resumes it.
	#
	# @id: The job identifier.
	#
	# Since: 3.0
	##
	{ 'command': 'job-pause', 'data': { 'id': 'str' } }

	##
	# @job-resume:
	#
	# Resume a paused job.
	#
	# This command returns immediately after resuming a paused job.
	# Resuming an already running job is an error.
	#
	# This command also clears the error status for block-jobs (stream,
	# commit, mirror, backup).
	#
	# @id: The job identifier.
	#
	# Since: 3.0
	##
	{ 'command': 'job-resume', 'data': { 'id': 'str' } }

	##
	# @job-cancel:
	#
	# Instruct an active background job to cancel at the next opportunity.
	# 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.
	#
	# @id: The job identifier.
	#
	# Since: 3.0
	##
	{ 'command': 'job-cancel', 'data': { 'id': 'str' } }

	##
	# @job-complete:
	#
	# 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, where it also switches
	# the device to write to the target path only. Note that drive
	# mirroring 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). The ability to complete is signaled with a
	# `BLOCK_JOB_READY` event.
	#
	# This command completes an active background block operation
	# synchronously. The ordering of this command's return with the
	# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O error
	# occurs during the processing of this command: 1) the command itself
	# will fail; 2) the error will be processed according to the
	# rerror/werror arguments that were specified when starting the
	# operation.
	#
	# @id: The job identifier.
	#
	# 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. In turn, automatic dismiss may be enabled only
	# for jobs that have @auto-dismiss option, which are `drive-backup`,
	# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and
	# `block-stream`. @auto-dismiss is enabled by default for these
	# jobs.
	#
	# This command will refuse to operate on any job that has not yet
	# reached its terminal state, CONCLUDED. For jobs that make use of
	# the JOB_READY event, `job-cancel` or `job-complete` will still need to
	# be used as appropriate.
	#
	# @id: The job identifier.
	#
	# 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.
	#
	# 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.
	#
	# The command is applicable only to jobs which have @auto-finalize option
	# and only when this option is set to false.
	#
	# @id: The identifier of any job in the transaction, or of a job that
	# is not part of any transaction.
	#
	# Since: 3.0
	##
	{ 'command': 'job-finalize', 'data': { 'id': 'str' } }

	##
	# @JobInfo:
	#
	# Information about a job.
	#
	# @id: The job identifier
	#
	# @type: The kind of job that is being performed
	#
	# @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.
	#
	# @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.
	#
	# The value is a human-readable error message to describe the
	# reason for the job failure. It should not be parsed by
	# applications.
	#
	# Since: 3.0
	##
	{ 'struct': 'JobInfo',
	'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus',
	'current-progress': 'int', 'total-progress': 'int',
	'*error': 'str' } }

	##
	# @query-jobs:
	#
	# Return information about jobs.
	#
	# Returns: a list with info for each active job
	#
	# Since: 3.0
	##
	{ 'command': 'query-jobs', 'returns': ['JobInfo'] }