blob: 1a6ef0345154e199f704a652106f501d7ca99dc1 [file] [log] [blame]
Kevin Wolfbf425082018-05-16 16:03:10 +02001# -*- Mode: Python -*-
Andrea Bolognanif7160f32020-07-29 20:50:24 +02002# vim: filetype=python
Kevin Wolfbf425082018-05-16 16:03:10 +02003
4##
5# == Background jobs
6##
7
8##
9# @JobType:
10#
11# Type of a background job.
12#
13# @commit: block commit job type, see "block-commit"
14#
15# @stream: block stream job type, see "block-stream"
16#
17# @mirror: drive mirror job type, see "drive-mirror"
18#
19# @backup: drive backup job type, see "drive-backup"
20#
Kevin Wolf3fb588a2018-05-25 18:24:51 +020021# @create: image creation job type, see "blockdev-create" (since 3.0)
Kevin Wolfe5ab4342018-01-18 14:33:04 +010022#
Maxim Levitskyced914d2020-06-25 14:55:45 +020023# @amend: image options amend job type, see "x-blockdev-amend" (since 5.1)
24#
Daniel P. Berrangé0f0d83a2021-02-04 12:48:34 +000025# @snapshot-load: snapshot load job type, see "snapshot-load" (since 6.0)
26#
27# @snapshot-save: snapshot save job type, see "snapshot-save" (since 6.0)
28#
29# @snapshot-delete: snapshot delete job type, see "snapshot-delete" (since 6.0)
30#
Kevin Wolfbf425082018-05-16 16:03:10 +020031# Since: 1.7
32##
33{ 'enum': 'JobType',
Daniel P. Berrangé0f0d83a2021-02-04 12:48:34 +000034 'data': ['commit', 'stream', 'mirror', 'backup', 'create', 'amend',
35 'snapshot-load', 'snapshot-save', 'snapshot-delete'] }
Kevin Wolfbf425082018-05-16 16:03:10 +020036
37##
38# @JobStatus:
39#
40# Indicates the present state of a given job in its lifetime.
41#
42# @undefined: Erroneous, default state. Should not ever be visible.
43#
44# @created: The job has been created, but not yet started.
45#
46# @running: The job is currently running.
47#
48# @paused: The job is running, but paused. The pause may be requested by
49# either the QMP user or by internal processes.
50#
51# @ready: The job is running, but is ready for the user to signal completion.
52# This is used for long-running jobs like mirror that are designed to
53# run indefinitely.
54#
55# @standby: The job is ready, but paused. This is nearly identical to @paused.
56# The job may return to @ready or otherwise be canceled.
57#
58# @waiting: The job is waiting for other jobs in the transaction to converge
59# to the waiting state. This status will likely not be visible for
60# the last job in a transaction.
61#
62# @pending: The job has finished its work, but has finalization steps that it
John Snowc5b09f32018-06-06 19:02:56 -040063# needs to make prior to completing. These changes will require
64# manual intervention via @job-finalize if auto-finalize was set to
65# false. These pending changes may still fail.
Kevin Wolfbf425082018-05-16 16:03:10 +020066#
67# @aborting: The job is in the process of being aborted, and will finish with
68# an error. The job will afterwards report that it is @concluded.
69# This status may not be visible to the management process.
70#
John Snowc5b09f32018-06-06 19:02:56 -040071# @concluded: The job has finished all work. If auto-dismiss was set to false,
72# the job will remain in the query list until it is dismissed via
73# @job-dismiss.
Kevin Wolfbf425082018-05-16 16:03:10 +020074#
75# @null: The job is in the process of being dismantled. This state should not
76# ever be visible externally.
77#
78# Since: 2.12
79##
80{ 'enum': 'JobStatus',
81 'data': ['undefined', 'created', 'running', 'paused', 'ready', 'standby',
82 'waiting', 'pending', 'aborting', 'concluded', 'null' ] }
83
84##
85# @JobVerb:
86#
87# Represents command verbs that can be applied to a job.
88#
John Snowb8a366f2018-06-06 19:02:57 -040089# @cancel: see @job-cancel
Kevin Wolfbf425082018-05-16 16:03:10 +020090#
John Snowb8a366f2018-06-06 19:02:57 -040091# @pause: see @job-pause
Kevin Wolfbf425082018-05-16 16:03:10 +020092#
John Snowb8a366f2018-06-06 19:02:57 -040093# @resume: see @job-resume
Kevin Wolfbf425082018-05-16 16:03:10 +020094#
95# @set-speed: see @block-job-set-speed
96#
John Snowb8a366f2018-06-06 19:02:57 -040097# @complete: see @job-complete
Kevin Wolfbf425082018-05-16 16:03:10 +020098#
John Snowb8a366f2018-06-06 19:02:57 -040099# @dismiss: see @job-dismiss
Kevin Wolfbf425082018-05-16 16:03:10 +0200100#
John Snowb8a366f2018-06-06 19:02:57 -0400101# @finalize: see @job-finalize
Kevin Wolfbf425082018-05-16 16:03:10 +0200102#
103# Since: 2.12
104##
105{ 'enum': 'JobVerb',
106 'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
107 'finalize' ] }
Kevin Wolf1dac83f2018-04-30 19:09:46 +0200108
109##
110# @JOB_STATUS_CHANGE:
111#
112# Emitted when a job transitions to a different status.
113#
114# @id: The job identifier
115# @status: The new job status
116#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200117# Since: 3.0
Kevin Wolf1dac83f2018-04-30 19:09:46 +0200118##
119{ 'event': 'JOB_STATUS_CHANGE',
120 'data': { 'id': 'str',
121 'status': 'JobStatus' } }
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200122
123##
124# @job-pause:
125#
126# Pause an active job.
127#
128# This command returns immediately after marking the active job for pausing.
129# Pausing an already paused job is an error.
130#
131# The job will pause as soon as possible, which means transitioning into the
132# PAUSED state if it was RUNNING, or into STANDBY if it was READY. The
133# corresponding JOB_STATUS_CHANGE event will be emitted.
134#
135# Cancelling a paused job automatically resumes it.
136#
137# @id: The job identifier.
138#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200139# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200140##
141{ 'command': 'job-pause', 'data': { 'id': 'str' } }
142
143##
144# @job-resume:
145#
146# Resume a paused job.
147#
148# This command returns immediately after resuming a paused job. Resuming an
149# already running job is an error.
150#
151# @id : The job identifier.
152#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200153# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200154##
155{ 'command': 'job-resume', 'data': { 'id': 'str' } }
156
157##
158# @job-cancel:
159#
160# Instruct an active background job to cancel at the next opportunity.
161# This command returns immediately after marking the active job for
162# cancellation.
163#
164# The job will cancel as soon as possible and then emit a JOB_STATUS_CHANGE
165# event. Usually, the status will change to ABORTING, but it is possible that
166# a job successfully completes (e.g. because it was almost done and there was
167# no opportunity to cancel earlier than completing the job) and transitions to
168# PENDING instead.
169#
170# @id: The job identifier.
171#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200172# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200173##
174{ 'command': 'job-cancel', 'data': { 'id': 'str' } }
175
176
177##
178# @job-complete:
179#
180# Manually trigger completion of an active job in the READY state.
181#
182# @id: The job identifier.
183#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200184# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200185##
186{ 'command': 'job-complete', 'data': { 'id': 'str' } }
187
188##
189# @job-dismiss:
190#
191# Deletes a job that is in the CONCLUDED state. This command only needs to be
192# run explicitly for jobs that don't have automatic dismiss enabled.
193#
194# This command will refuse to operate on any job that has not yet reached its
195# terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of JOB_READY
196# event, job-cancel or job-complete will still need to be used as appropriate.
197#
198# @id: The job identifier.
199#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200200# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200201##
202{ 'command': 'job-dismiss', 'data': { 'id': 'str' } }
203
204##
205# @job-finalize:
206#
207# Instructs all jobs in a transaction (or a single job if it is not part of any
208# transaction) to finalize any graph changes and do any necessary cleanup. This
209# command requires that all involved jobs are in the PENDING state.
210#
211# For jobs in a transaction, instructing one job to finalize will force
212# ALL jobs in the transaction to finalize, so it is only necessary to instruct
213# a single member job to finalize.
214#
215# @id: The identifier of any job in the transaction, or of a job that is not
216# part of any transaction.
217#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200218# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200219##
220{ 'command': 'job-finalize', 'data': { 'id': 'str' } }
Kevin Wolf456273b2018-05-04 16:25:43 +0200221
222##
223# @JobInfo:
224#
225# Information about a job.
226#
Peter Maydell26ec4e52020-02-13 17:56:26 +0000227# @id: The job identifier
Kevin Wolf456273b2018-05-04 16:25:43 +0200228#
Peter Maydell26ec4e52020-02-13 17:56:26 +0000229# @type: The kind of job that is being performed
Kevin Wolf456273b2018-05-04 16:25:43 +0200230#
Peter Maydell26ec4e52020-02-13 17:56:26 +0000231# @status: Current job state/status
Kevin Wolf456273b2018-05-04 16:25:43 +0200232#
Peter Maydell26ec4e52020-02-13 17:56:26 +0000233# @current-progress: Progress made until now. The unit is arbitrary and the
234# value can only meaningfully be used for the ratio of
235# @current-progress to @total-progress. The value is
236# monotonically increasing.
Kevin Wolf456273b2018-05-04 16:25:43 +0200237#
Peter Maydell26ec4e52020-02-13 17:56:26 +0000238# @total-progress: Estimated @current-progress value at the completion of
239# the job. This value can arbitrarily change while the
240# job is running, in both directions.
Kevin Wolf456273b2018-05-04 16:25:43 +0200241#
Peter Maydell26ec4e52020-02-13 17:56:26 +0000242# @error: If this field is present, the job failed; if it is
243# still missing in the CONCLUDED state, this indicates
244# successful completion.
Kevin Wolf456273b2018-05-04 16:25:43 +0200245#
Peter Maydell26ec4e52020-02-13 17:56:26 +0000246# The value is a human-readable error message to describe
247# the reason for the job failure. It should not be parsed
248# by applications.
Kevin Wolf456273b2018-05-04 16:25:43 +0200249#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200250# Since: 3.0
Kevin Wolf456273b2018-05-04 16:25:43 +0200251##
252{ 'struct': 'JobInfo',
253 'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus',
254 'current-progress': 'int', 'total-progress': 'int',
255 '*error': 'str' } }
256
257##
258# @query-jobs:
259#
260# Return information about jobs.
261#
262# Returns: a list with a @JobInfo for each active job
263#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200264# Since: 3.0
Kevin Wolf456273b2018-05-04 16:25:43 +0200265##
266{ 'command': 'query-jobs', 'returns': ['JobInfo'] }