# -*- 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'] }