2018-05-16 16:03:10 +02:00
|
|
|
# -*- Mode: Python -*-
|
2020-07-29 20:50:24 +02:00
|
|
|
# vim: filetype=python
|
2018-05-16 16:03:10 +02:00
|
|
|
|
|
|
|
##
|
|
|
|
# == 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"
|
|
|
|
#
|
2018-05-25 18:24:51 +02:00
|
|
|
# @create: image creation job type, see "blockdev-create" (since 3.0)
|
2018-01-18 14:33:04 +01:00
|
|
|
#
|
2020-06-25 14:55:45 +02:00
|
|
|
# @amend: image options amend job type, see "x-blockdev-amend" (since 5.1)
|
|
|
|
#
|
migration: introduce snapshot-{save, load, delete} QMP commands
savevm, loadvm and delvm are some of the few HMP commands that have never
been converted to use QMP. The reasons for the lack of conversion are
that they blocked execution of the event thread, and the semantics
around choice of disks were ill-defined.
Despite this downside, however, libvirt and applications using libvirt
have used these commands for as long as QMP has existed, via the
"human-monitor-command" passthrough command. IOW, while it is clearly
desirable to be able to fix the problems, they are not a blocker to
all real world usage.
Meanwhile there is a need for other features which involve adding new
parameters to the commands. This is possible with HMP passthrough, but
it provides no reliable way for apps to introspect features, so using
QAPI modelling is highly desirable.
This patch thus introduces new snapshot-{load,save,delete} commands to
QMP that are intended to replace the old HMP counterparts. The new
commands are given different names, because they will be using the new
QEMU job framework and thus will have diverging behaviour from the HMP
originals. It would thus be misleading to keep the same name.
While this design uses the generic job framework, the current impl is
still blocking. The intention that the blocking problem is fixed later.
None the less applications using these new commands should assume that
they are asynchronous and thus wait for the job status change event to
indicate completion.
In addition to using the job framework, the new commands require the
caller to be explicit about all the block device nodes used in the
snapshot operations, with no built-in default heuristics in use.
Note that the existing "query-named-block-nodes" can be used to query
what snapshots currently exist for block nodes.
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Message-Id: <20210204124834.774401-13-berrange@redhat.com>
Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
dgilbert: removed tests for now, the output ordering isn't
deterministic
2021-02-04 13:48:34 +01:00
|
|
|
# @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)
|
|
|
|
#
|
2018-05-16 16:03:10 +02:00
|
|
|
# Since: 1.7
|
|
|
|
##
|
|
|
|
{ 'enum': 'JobType',
|
migration: introduce snapshot-{save, load, delete} QMP commands
savevm, loadvm and delvm are some of the few HMP commands that have never
been converted to use QMP. The reasons for the lack of conversion are
that they blocked execution of the event thread, and the semantics
around choice of disks were ill-defined.
Despite this downside, however, libvirt and applications using libvirt
have used these commands for as long as QMP has existed, via the
"human-monitor-command" passthrough command. IOW, while it is clearly
desirable to be able to fix the problems, they are not a blocker to
all real world usage.
Meanwhile there is a need for other features which involve adding new
parameters to the commands. This is possible with HMP passthrough, but
it provides no reliable way for apps to introspect features, so using
QAPI modelling is highly desirable.
This patch thus introduces new snapshot-{load,save,delete} commands to
QMP that are intended to replace the old HMP counterparts. The new
commands are given different names, because they will be using the new
QEMU job framework and thus will have diverging behaviour from the HMP
originals. It would thus be misleading to keep the same name.
While this design uses the generic job framework, the current impl is
still blocking. The intention that the blocking problem is fixed later.
None the less applications using these new commands should assume that
they are asynchronous and thus wait for the job status change event to
indicate completion.
In addition to using the job framework, the new commands require the
caller to be explicit about all the block device nodes used in the
snapshot operations, with no built-in default heuristics in use.
Note that the existing "query-named-block-nodes" can be used to query
what snapshots currently exist for block nodes.
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Message-Id: <20210204124834.774401-13-berrange@redhat.com>
Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
dgilbert: removed tests for now, the output ordering isn't
deterministic
2021-02-04 13:48:34 +01:00
|
|
|
'data': ['commit', 'stream', 'mirror', 'backup', 'create', 'amend',
|
|
|
|
'snapshot-load', 'snapshot-save', 'snapshot-delete'] }
|
2018-05-16 16:03:10 +02:00
|
|
|
|
|
|
|
##
|
|
|
|
# @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
|
2018-06-07 01:02:56 +02:00
|
|
|
# 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.
|
2018-05-16 16:03:10 +02:00
|
|
|
#
|
|
|
|
# @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.
|
|
|
|
#
|
2018-06-07 01:02:56 +02:00
|
|
|
# @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.
|
2018-05-16 16:03:10 +02:00
|
|
|
#
|
|
|
|
# @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.
|
|
|
|
#
|
2018-06-07 01:02:57 +02:00
|
|
|
# @cancel: see @job-cancel
|
2018-05-16 16:03:10 +02:00
|
|
|
#
|
2018-06-07 01:02:57 +02:00
|
|
|
# @pause: see @job-pause
|
2018-05-16 16:03:10 +02:00
|
|
|
#
|
2018-06-07 01:02:57 +02:00
|
|
|
# @resume: see @job-resume
|
2018-05-16 16:03:10 +02:00
|
|
|
#
|
|
|
|
# @set-speed: see @block-job-set-speed
|
|
|
|
#
|
2018-06-07 01:02:57 +02:00
|
|
|
# @complete: see @job-complete
|
2018-05-16 16:03:10 +02:00
|
|
|
#
|
2018-06-07 01:02:57 +02:00
|
|
|
# @dismiss: see @job-dismiss
|
2018-05-16 16:03:10 +02:00
|
|
|
#
|
2018-06-07 01:02:57 +02:00
|
|
|
# @finalize: see @job-finalize
|
2018-05-16 16:03:10 +02:00
|
|
|
#
|
|
|
|
# Since: 2.12
|
|
|
|
##
|
|
|
|
{ 'enum': 'JobVerb',
|
|
|
|
'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
|
|
|
|
'finalize' ] }
|
2018-04-30 19:09:46 +02:00
|
|
|
|
|
|
|
##
|
|
|
|
# @JOB_STATUS_CHANGE:
|
|
|
|
#
|
|
|
|
# Emitted when a job transitions to a different status.
|
|
|
|
#
|
|
|
|
# @id: The job identifier
|
|
|
|
# @status: The new job status
|
|
|
|
#
|
2018-06-26 10:37:02 +02:00
|
|
|
# Since: 3.0
|
2018-04-30 19:09:46 +02:00
|
|
|
##
|
|
|
|
{ 'event': 'JOB_STATUS_CHANGE',
|
|
|
|
'data': { 'id': 'str',
|
|
|
|
'status': 'JobStatus' } }
|
2018-05-03 19:01:14 +02:00
|
|
|
|
|
|
|
##
|
|
|
|
# @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.
|
|
|
|
#
|
2018-06-26 10:37:02 +02:00
|
|
|
# Since: 3.0
|
2018-05-03 19:01:14 +02:00
|
|
|
##
|
|
|
|
{ '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.
|
|
|
|
#
|
2018-06-26 10:37:02 +02:00
|
|
|
# Since: 3.0
|
2018-05-03 19:01:14 +02:00
|
|
|
##
|
|
|
|
{ '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.
|
|
|
|
#
|
2018-06-26 10:37:02 +02:00
|
|
|
# Since: 3.0
|
2018-05-03 19:01:14 +02:00
|
|
|
##
|
|
|
|
{ 'command': 'job-cancel', 'data': { 'id': 'str' } }
|
|
|
|
|
|
|
|
|
|
|
|
##
|
|
|
|
# @job-complete:
|
|
|
|
#
|
|
|
|
# Manually trigger completion of an active job in the READY state.
|
|
|
|
#
|
|
|
|
# @id: The job identifier.
|
|
|
|
#
|
2018-06-26 10:37:02 +02:00
|
|
|
# Since: 3.0
|
2018-05-03 19:01:14 +02:00
|
|
|
##
|
|
|
|
{ '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.
|
|
|
|
#
|
2018-06-26 10:37:02 +02:00
|
|
|
# Since: 3.0
|
2018-05-03 19:01:14 +02:00
|
|
|
##
|
|
|
|
{ '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.
|
|
|
|
#
|
2018-06-26 10:37:02 +02:00
|
|
|
# Since: 3.0
|
2018-05-03 19:01:14 +02:00
|
|
|
##
|
|
|
|
{ 'command': 'job-finalize', 'data': { 'id': 'str' } }
|
2018-05-04 16:25:43 +02:00
|
|
|
|
|
|
|
##
|
|
|
|
# @JobInfo:
|
|
|
|
#
|
|
|
|
# Information about a job.
|
|
|
|
#
|
2020-02-13 18:56:26 +01:00
|
|
|
# @id: The job identifier
|
2018-05-04 16:25:43 +02:00
|
|
|
#
|
2020-02-13 18:56:26 +01:00
|
|
|
# @type: The kind of job that is being performed
|
2018-05-04 16:25:43 +02:00
|
|
|
#
|
2020-02-13 18:56:26 +01:00
|
|
|
# @status: Current job state/status
|
2018-05-04 16:25:43 +02:00
|
|
|
#
|
2020-02-13 18:56:26 +01:00
|
|
|
# @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.
|
2018-05-04 16:25:43 +02:00
|
|
|
#
|
2020-02-13 18:56:26 +01:00
|
|
|
# @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.
|
2018-05-04 16:25:43 +02:00
|
|
|
#
|
2020-02-13 18:56:26 +01:00
|
|
|
# @error: If this field is present, the job failed; if it is
|
|
|
|
# still missing in the CONCLUDED state, this indicates
|
|
|
|
# successful completion.
|
2018-05-04 16:25:43 +02:00
|
|
|
#
|
2020-02-13 18:56:26 +01:00
|
|
|
# The value is a human-readable error message to describe
|
|
|
|
# the reason for the job failure. It should not be parsed
|
|
|
|
# by applications.
|
2018-05-04 16:25:43 +02:00
|
|
|
#
|
2018-06-26 10:37:02 +02:00
|
|
|
# Since: 3.0
|
2018-05-04 16:25:43 +02:00
|
|
|
##
|
|
|
|
{ '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
|
|
|
|
#
|
2018-06-26 10:37:02 +02:00
|
|
|
# Since: 3.0
|
2018-05-04 16:25:43 +02:00
|
|
|
##
|
|
|
|
{ 'command': 'query-jobs', 'returns': ['JobInfo'] }
|