blob: a121b615fb07f169f2f968ce3678f51e9054b7a3 [file] [log] [blame]
Kevin Wolfbf425082018-05-16 16:03:10 +02001# -*- Mode: Python -*-
2
3##
4# == Background jobs
5##
6
7##
8# @JobType:
9#
10# Type of a background job.
11#
12# @commit: block commit job type, see "block-commit"
13#
14# @stream: block stream job type, see "block-stream"
15#
16# @mirror: drive mirror job type, see "drive-mirror"
17#
18# @backup: drive backup job type, see "drive-backup"
19#
Kevin Wolf3fb588a2018-05-25 18:24:51 +020020# @create: image creation job type, see "blockdev-create" (since 3.0)
Kevin Wolfe5ab4342018-01-18 14:33:04 +010021#
Kevin Wolfbf425082018-05-16 16:03:10 +020022# Since: 1.7
23##
24{ 'enum': 'JobType',
Kevin Wolfe5ab4342018-01-18 14:33:04 +010025 'data': ['commit', 'stream', 'mirror', 'backup', 'create'] }
Kevin Wolfbf425082018-05-16 16:03:10 +020026
27##
28# @JobStatus:
29#
30# Indicates the present state of a given job in its lifetime.
31#
32# @undefined: Erroneous, default state. Should not ever be visible.
33#
34# @created: The job has been created, but not yet started.
35#
36# @running: The job is currently running.
37#
38# @paused: The job is running, but paused. The pause may be requested by
39# either the QMP user or by internal processes.
40#
41# @ready: The job is running, but is ready for the user to signal completion.
42# This is used for long-running jobs like mirror that are designed to
43# run indefinitely.
44#
45# @standby: The job is ready, but paused. This is nearly identical to @paused.
46# The job may return to @ready or otherwise be canceled.
47#
48# @waiting: The job is waiting for other jobs in the transaction to converge
49# to the waiting state. This status will likely not be visible for
50# the last job in a transaction.
51#
52# @pending: The job has finished its work, but has finalization steps that it
John Snowc5b09f32018-06-06 19:02:56 -040053# needs to make prior to completing. These changes will require
54# manual intervention via @job-finalize if auto-finalize was set to
55# false. These pending changes may still fail.
Kevin Wolfbf425082018-05-16 16:03:10 +020056#
57# @aborting: The job is in the process of being aborted, and will finish with
58# an error. The job will afterwards report that it is @concluded.
59# This status may not be visible to the management process.
60#
John Snowc5b09f32018-06-06 19:02:56 -040061# @concluded: The job has finished all work. If auto-dismiss was set to false,
62# the job will remain in the query list until it is dismissed via
63# @job-dismiss.
Kevin Wolfbf425082018-05-16 16:03:10 +020064#
65# @null: The job is in the process of being dismantled. This state should not
66# ever be visible externally.
67#
68# Since: 2.12
69##
70{ 'enum': 'JobStatus',
71 'data': ['undefined', 'created', 'running', 'paused', 'ready', 'standby',
72 'waiting', 'pending', 'aborting', 'concluded', 'null' ] }
73
74##
75# @JobVerb:
76#
77# Represents command verbs that can be applied to a job.
78#
John Snowb8a366f2018-06-06 19:02:57 -040079# @cancel: see @job-cancel
Kevin Wolfbf425082018-05-16 16:03:10 +020080#
John Snowb8a366f2018-06-06 19:02:57 -040081# @pause: see @job-pause
Kevin Wolfbf425082018-05-16 16:03:10 +020082#
John Snowb8a366f2018-06-06 19:02:57 -040083# @resume: see @job-resume
Kevin Wolfbf425082018-05-16 16:03:10 +020084#
85# @set-speed: see @block-job-set-speed
86#
John Snowb8a366f2018-06-06 19:02:57 -040087# @complete: see @job-complete
Kevin Wolfbf425082018-05-16 16:03:10 +020088#
John Snowb8a366f2018-06-06 19:02:57 -040089# @dismiss: see @job-dismiss
Kevin Wolfbf425082018-05-16 16:03:10 +020090#
John Snowb8a366f2018-06-06 19:02:57 -040091# @finalize: see @job-finalize
Kevin Wolfbf425082018-05-16 16:03:10 +020092#
93# Since: 2.12
94##
95{ 'enum': 'JobVerb',
96 'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
97 'finalize' ] }
Kevin Wolf1dac83f2018-04-30 19:09:46 +020098
99##
100# @JOB_STATUS_CHANGE:
101#
102# Emitted when a job transitions to a different status.
103#
104# @id: The job identifier
105# @status: The new job status
106#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200107# Since: 3.0
Kevin Wolf1dac83f2018-04-30 19:09:46 +0200108##
109{ 'event': 'JOB_STATUS_CHANGE',
110 'data': { 'id': 'str',
111 'status': 'JobStatus' } }
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200112
113##
114# @job-pause:
115#
116# Pause an active job.
117#
118# This command returns immediately after marking the active job for pausing.
119# Pausing an already paused job is an error.
120#
121# The job will pause as soon as possible, which means transitioning into the
122# PAUSED state if it was RUNNING, or into STANDBY if it was READY. The
123# corresponding JOB_STATUS_CHANGE event will be emitted.
124#
125# Cancelling a paused job automatically resumes it.
126#
127# @id: The job identifier.
128#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200129# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200130##
131{ 'command': 'job-pause', 'data': { 'id': 'str' } }
132
133##
134# @job-resume:
135#
136# Resume a paused job.
137#
138# This command returns immediately after resuming a paused job. Resuming an
139# already running job is an error.
140#
141# @id : The job identifier.
142#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200143# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200144##
145{ 'command': 'job-resume', 'data': { 'id': 'str' } }
146
147##
148# @job-cancel:
149#
150# Instruct an active background job to cancel at the next opportunity.
151# This command returns immediately after marking the active job for
152# cancellation.
153#
154# The job will cancel as soon as possible and then emit a JOB_STATUS_CHANGE
155# event. Usually, the status will change to ABORTING, but it is possible that
156# a job successfully completes (e.g. because it was almost done and there was
157# no opportunity to cancel earlier than completing the job) and transitions to
158# PENDING instead.
159#
160# @id: The job identifier.
161#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200162# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200163##
164{ 'command': 'job-cancel', 'data': { 'id': 'str' } }
165
166
167##
168# @job-complete:
169#
170# Manually trigger completion of an active job in the READY state.
171#
172# @id: The job identifier.
173#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200174# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200175##
176{ 'command': 'job-complete', 'data': { 'id': 'str' } }
177
178##
179# @job-dismiss:
180#
181# Deletes a job that is in the CONCLUDED state. This command only needs to be
182# run explicitly for jobs that don't have automatic dismiss enabled.
183#
184# This command will refuse to operate on any job that has not yet reached its
185# terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of JOB_READY
186# event, job-cancel or job-complete will still need to be used as appropriate.
187#
188# @id: The job identifier.
189#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200190# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200191##
192{ 'command': 'job-dismiss', 'data': { 'id': 'str' } }
193
194##
195# @job-finalize:
196#
197# Instructs all jobs in a transaction (or a single job if it is not part of any
198# transaction) to finalize any graph changes and do any necessary cleanup. This
199# command requires that all involved jobs are in the PENDING state.
200#
201# For jobs in a transaction, instructing one job to finalize will force
202# ALL jobs in the transaction to finalize, so it is only necessary to instruct
203# a single member job to finalize.
204#
205# @id: The identifier of any job in the transaction, or of a job that is not
206# part of any transaction.
207#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200208# Since: 3.0
Kevin Wolf1a90bc82018-05-03 19:01:14 +0200209##
210{ 'command': 'job-finalize', 'data': { 'id': 'str' } }
Kevin Wolf456273b2018-05-04 16:25:43 +0200211
212##
213# @JobInfo:
214#
215# Information about a job.
216#
217# @id: The job identifier
218#
219# @type: The kind of job that is being performed
220#
221# @status: Current job state/status
222#
223# @current-progress: Progress made until now. The unit is arbitrary and the
224# value can only meaningfully be used for the ratio of
225# @current-progress to @total-progress. The value is
226# monotonically increasing.
227#
228# @total-progress: Estimated @current-progress value at the completion of
229# the job. This value can arbitrarily change while the
230# job is running, in both directions.
231#
232# @error: If this field is present, the job failed; if it is
233# still missing in the CONCLUDED state, this indicates
234# successful completion.
235#
236# The value is a human-readable error message to describe
237# the reason for the job failure. It should not be parsed
238# by applications.
239#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200240# Since: 3.0
Kevin Wolf456273b2018-05-04 16:25:43 +0200241##
242{ 'struct': 'JobInfo',
243 'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus',
244 'current-progress': 'int', 'total-progress': 'int',
245 '*error': 'str' } }
246
247##
248# @query-jobs:
249#
250# Return information about jobs.
251#
252# Returns: a list with a @JobInfo for each active job
253#
Kevin Wolf0ab1c412018-06-26 10:37:02 +0200254# Since: 3.0
Kevin Wolf456273b2018-05-04 16:25:43 +0200255##
256{ 'command': 'query-jobs', 'returns': ['JobInfo'] }