qapi/job.json - qemu - Git at Google

 # -*- Mode: 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)
 #
 # Since: 1.7
 ##
 { 'enum': 'JobType',
   'data': ['commit', 'stream', 'mirror', 'backup', 'create'] }

 ##
 # @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 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.
 #
 # 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
 #
 # Since: 2.12
 ##
 { 'enum': 'JobVerb',
   'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
            'finalize' ] }

 ##
 # @JOB_STATUS_CHANGE:
 #
 # Emitted when a job transitions to a different status.
 #
 # @id: The job identifier
 # @status: The new job status
 #
 # Since: 2.13
 ##
 { '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: 2.13
 ##
 { '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.
 #
 # @id : The job identifier.
 #
 # Since: 2.13
 ##
 { '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: 2.13
 ##
 { 'command': 'job-cancel', 'data': { 'id': 'str' } }


 ##
 # @job-complete:
 #
 # Manually trigger completion of an active job in the READY state.
 #
 # @id: The job identifier.
 #
 # Since: 2.13
 ##
 { '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.
 #
 # 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
 ##
 { '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.
 #
 # @id: The identifier of any job in the transaction, or of a job that is not
 #      part of any transaction.
 #
 # Since: 2.13
 ##
 { '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: 2.13
 ##
 { '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 a @JobInfo for each active job
 #
 # Since: 2.13
 ##
 { 'command': 'query-jobs', 'returns': ['JobInfo'] }
	# -- Mode: 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)
	#
	# Since: 1.7
	##
	{ 'enum': 'JobType',
	'data': ['commit', 'stream', 'mirror', 'backup', 'create'] }

	##
	# @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 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.
	#
	# 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
	#
	# Since: 2.12
	##
	{ 'enum': 'JobVerb',
	'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
	'finalize' ] }

	##
	# @JOB_STATUS_CHANGE:
	#
	# Emitted when a job transitions to a different status.
	#
	# @id: The job identifier
	# @status: The new job status
	#
	# Since: 2.13
	##
	{ '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: 2.13
	##
	{ '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.
	#
	# @id : The job identifier.
	#
	# Since: 2.13
	##
	{ '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: 2.13
	##
	{ 'command': 'job-cancel', 'data': { 'id': 'str' } }


	##
	# @job-complete:
	#
	# Manually trigger completion of an active job in the READY state.
	#
	# @id: The job identifier.
	#
	# Since: 2.13
	##
	{ '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.
	#
	# 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
	##
	{ '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.
	#
	# @id: The identifier of any job in the transaction, or of a job that is not
	# part of any transaction.
	#
	# Since: 2.13
	##
	{ '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: 2.13
	##
	{ '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 a @JobInfo for each active job
	#
	# Since: 2.13
	##
	{ 'command': 'query-jobs', 'returns': ['JobInfo'] }