257 lines
7.2 KiB
Python
257 lines
7.2 KiB
Python
# -*- 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: 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.
|
|
#
|
|
# @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 state.
|
|
#
|
|
# @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.
|
|
#
|
|
# 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: 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.
|
|
#
|
|
# @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 a @JobInfo for each active job
|
|
#
|
|
# Since: 3.0
|
|
##
|
|
{ 'command': 'query-jobs', 'returns': ['JobInfo'] }
|