qemu/qapi/job.json
Andrea Bolognani f7160f3218 schemas: Add vim modeline
The various schemas included in QEMU use a JSON-based format which
is, however, strictly speaking not valid JSON.

As a consequence, when vim tries to apply syntax highlight rules
for JSON (as guessed from the file name), the result is an unreadable
mess which mostly consist of red markers pointing out supposed errors
in, well, pretty much everything.

Using Python syntax highlighting produces much better results, and
in fact these files already start with specially-formatted comments
that instruct Emacs to process them as if they were Python files.

This commit adds the equivalent special comments for vim.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Message-Id: <20200729185024.121766-1-abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-08-03 08:28:08 +02:00

260 lines
7.1 KiB
Python

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