summaryrefslogtreecommitdiff
path: root/qapi/job.json
blob: 1a6ef0345154e199f704a652106f501d7ca99dc1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
# -*- 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 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'] }