]>
Commit | Line | Data |
---|---|---|
bf42508f | 1 | # -*- Mode: Python -*- |
f7160f32 | 2 | # vim: filetype=python |
bf42508f KW |
3 | |
4 | ## | |
4622c706 | 5 | # = Background jobs |
bf42508f KW |
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 | # | |
3fb588a0 | 21 | # @create: image creation job type, see "blockdev-create" (since 3.0) |
e5ab4347 | 22 | # |
a937b6aa MA |
23 | # @amend: image options amend job type, see "x-blockdev-amend" (since |
24 | # 5.1) | |
ced914d0 | 25 | # |
a937b6aa MA |
26 | # @snapshot-load: snapshot load job type, see "snapshot-load" (since |
27 | # 6.0) | |
0f0d83a4 | 28 | # |
a937b6aa MA |
29 | # @snapshot-save: snapshot save job type, see "snapshot-save" (since |
30 | # 6.0) | |
0f0d83a4 | 31 | # |
a937b6aa MA |
32 | # @snapshot-delete: snapshot delete job type, see "snapshot-delete" |
33 | # (since 6.0) | |
0f0d83a4 | 34 | # |
bf42508f KW |
35 | # Since: 1.7 |
36 | ## | |
37 | { 'enum': 'JobType', | |
0f0d83a4 DB |
38 | 'data': ['commit', 'stream', 'mirror', 'backup', 'create', 'amend', |
39 | 'snapshot-load', 'snapshot-save', 'snapshot-delete'] } | |
bf42508f KW |
40 | |
41 | ## | |
42 | # @JobStatus: | |
43 | # | |
44 | # Indicates the present state of a given job in its lifetime. | |
45 | # | |
a937b6aa | 46 | # @undefined: Erroneous, default state. Should not ever be visible. |
bf42508f KW |
47 | # |
48 | # @created: The job has been created, but not yet started. | |
49 | # | |
50 | # @running: The job is currently running. | |
51 | # | |
a937b6aa MA |
52 | # @paused: The job is running, but paused. The pause may be requested |
53 | # by either the QMP user or by internal processes. | |
bf42508f | 54 | # |
a937b6aa MA |
55 | # @ready: The job is running, but is ready for the user to signal |
56 | # completion. This is used for long-running jobs like mirror that | |
57 | # are designed to run indefinitely. | |
bf42508f | 58 | # |
a937b6aa MA |
59 | # @standby: The job is ready, but paused. This is nearly identical to |
60 | # @paused. The job may return to @ready or otherwise be canceled. | |
bf42508f | 61 | # |
a937b6aa MA |
62 | # @waiting: The job is waiting for other jobs in the transaction to |
63 | # converge to the waiting state. This status will likely not be | |
64 | # visible for the last job in a transaction. | |
bf42508f | 65 | # |
a937b6aa MA |
66 | # @pending: The job has finished its work, but has finalization steps |
67 | # that it needs to make prior to completing. These changes will | |
68 | # require manual intervention via @job-finalize if auto-finalize | |
69 | # was set to false. These pending changes may still fail. | |
bf42508f | 70 | # |
a937b6aa MA |
71 | # @aborting: The job is in the process of being aborted, and will |
72 | # finish with an error. The job will afterwards report that it is | |
73 | # @concluded. This status may not be visible to the management | |
74 | # process. | |
bf42508f | 75 | # |
a937b6aa MA |
76 | # @concluded: The job has finished all work. If auto-dismiss was set |
77 | # to false, the job will remain in the query list until it is | |
78 | # dismissed via @job-dismiss. | |
bf42508f | 79 | # |
a937b6aa MA |
80 | # @null: The job is in the process of being dismantled. This state |
81 | # should not ever be visible externally. | |
bf42508f KW |
82 | # |
83 | # Since: 2.12 | |
84 | ## | |
85 | { 'enum': 'JobStatus', | |
86 | 'data': ['undefined', 'created', 'running', 'paused', 'ready', 'standby', | |
87 | 'waiting', 'pending', 'aborting', 'concluded', 'null' ] } | |
88 | ||
89 | ## | |
90 | # @JobVerb: | |
91 | # | |
92 | # Represents command verbs that can be applied to a job. | |
93 | # | |
b8a366fe | 94 | # @cancel: see @job-cancel |
bf42508f | 95 | # |
b8a366fe | 96 | # @pause: see @job-pause |
bf42508f | 97 | # |
b8a366fe | 98 | # @resume: see @job-resume |
bf42508f KW |
99 | # |
100 | # @set-speed: see @block-job-set-speed | |
101 | # | |
b8a366fe | 102 | # @complete: see @job-complete |
bf42508f | 103 | # |
b8a366fe | 104 | # @dismiss: see @job-dismiss |
bf42508f | 105 | # |
b8a366fe | 106 | # @finalize: see @job-finalize |
bf42508f | 107 | # |
61a3a5a7 FE |
108 | # @change: see @block-job-change (since 8.2) |
109 | # | |
bf42508f KW |
110 | # Since: 2.12 |
111 | ## | |
112 | { 'enum': 'JobVerb', | |
113 | 'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss', | |
61a3a5a7 | 114 | 'finalize', 'change' ] } |
1dac83f1 KW |
115 | |
116 | ## | |
117 | # @JOB_STATUS_CHANGE: | |
118 | # | |
119 | # Emitted when a job transitions to a different status. | |
120 | # | |
121 | # @id: The job identifier | |
a937b6aa | 122 | # |
1dac83f1 KW |
123 | # @status: The new job status |
124 | # | |
0ab1c41d | 125 | # Since: 3.0 |
1dac83f1 KW |
126 | ## |
127 | { 'event': 'JOB_STATUS_CHANGE', | |
128 | 'data': { 'id': 'str', | |
129 | 'status': 'JobStatus' } } | |
1a90bc81 KW |
130 | |
131 | ## | |
132 | # @job-pause: | |
133 | # | |
134 | # Pause an active job. | |
135 | # | |
a937b6aa MA |
136 | # This command returns immediately after marking the active job for |
137 | # pausing. Pausing an already paused job is an error. | |
1a90bc81 | 138 | # |
a937b6aa MA |
139 | # The job will pause as soon as possible, which means transitioning |
140 | # into the PAUSED state if it was RUNNING, or into STANDBY if it was | |
141 | # READY. The corresponding JOB_STATUS_CHANGE event will be emitted. | |
1a90bc81 KW |
142 | # |
143 | # Cancelling a paused job automatically resumes it. | |
144 | # | |
145 | # @id: The job identifier. | |
146 | # | |
0ab1c41d | 147 | # Since: 3.0 |
1a90bc81 KW |
148 | ## |
149 | { 'command': 'job-pause', 'data': { 'id': 'str' } } | |
150 | ||
151 | ## | |
152 | # @job-resume: | |
153 | # | |
154 | # Resume a paused job. | |
155 | # | |
a937b6aa MA |
156 | # This command returns immediately after resuming a paused job. |
157 | # Resuming an already running job is an error. | |
1a90bc81 | 158 | # |
91577c47 | 159 | # @id: The job identifier. |
1a90bc81 | 160 | # |
0ab1c41d | 161 | # Since: 3.0 |
1a90bc81 KW |
162 | ## |
163 | { 'command': 'job-resume', 'data': { 'id': 'str' } } | |
164 | ||
165 | ## | |
166 | # @job-cancel: | |
167 | # | |
168 | # Instruct an active background job to cancel at the next opportunity. | |
169 | # This command returns immediately after marking the active job for | |
170 | # cancellation. | |
171 | # | |
a937b6aa MA |
172 | # The job will cancel as soon as possible and then emit a |
173 | # JOB_STATUS_CHANGE event. Usually, the status will change to | |
174 | # ABORTING, but it is possible that a job successfully completes (e.g. | |
175 | # because it was almost done and there was no opportunity to cancel | |
176 | # earlier than completing the job) and transitions to PENDING instead. | |
1a90bc81 KW |
177 | # |
178 | # @id: The job identifier. | |
179 | # | |
0ab1c41d | 180 | # Since: 3.0 |
1a90bc81 KW |
181 | ## |
182 | { 'command': 'job-cancel', 'data': { 'id': 'str' } } | |
183 | ||
1a90bc81 KW |
184 | ## |
185 | # @job-complete: | |
186 | # | |
187 | # Manually trigger completion of an active job in the READY state. | |
188 | # | |
189 | # @id: The job identifier. | |
190 | # | |
0ab1c41d | 191 | # Since: 3.0 |
1a90bc81 KW |
192 | ## |
193 | { 'command': 'job-complete', 'data': { 'id': 'str' } } | |
194 | ||
195 | ## | |
196 | # @job-dismiss: | |
197 | # | |
a937b6aa MA |
198 | # Deletes a job that is in the CONCLUDED state. This command only |
199 | # needs to be run explicitly for jobs that don't have automatic | |
200 | # dismiss enabled. | |
1a90bc81 | 201 | # |
a937b6aa MA |
202 | # This command will refuse to operate on any job that has not yet |
203 | # reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that make | |
204 | # use of JOB_READY event, job-cancel or job-complete will still need | |
205 | # to be used as appropriate. | |
1a90bc81 KW |
206 | # |
207 | # @id: The job identifier. | |
208 | # | |
0ab1c41d | 209 | # Since: 3.0 |
1a90bc81 KW |
210 | ## |
211 | { 'command': 'job-dismiss', 'data': { 'id': 'str' } } | |
212 | ||
213 | ## | |
214 | # @job-finalize: | |
215 | # | |
a937b6aa MA |
216 | # Instructs all jobs in a transaction (or a single job if it is not |
217 | # part of any transaction) to finalize any graph changes and do any | |
218 | # necessary cleanup. This command requires that all involved jobs are | |
219 | # in the PENDING state. | |
1a90bc81 | 220 | # |
a937b6aa MA |
221 | # For jobs in a transaction, instructing one job to finalize will |
222 | # force ALL jobs in the transaction to finalize, so it is only | |
223 | # necessary to instruct a single member job to finalize. | |
1a90bc81 | 224 | # |
a937b6aa MA |
225 | # @id: The identifier of any job in the transaction, or of a job that |
226 | # is not part of any transaction. | |
1a90bc81 | 227 | # |
0ab1c41d | 228 | # Since: 3.0 |
1a90bc81 KW |
229 | ## |
230 | { 'command': 'job-finalize', 'data': { 'id': 'str' } } | |
456273b0 KW |
231 | |
232 | ## | |
233 | # @JobInfo: | |
234 | # | |
235 | # Information about a job. | |
236 | # | |
26ec4e53 | 237 | # @id: The job identifier |
456273b0 | 238 | # |
26ec4e53 | 239 | # @type: The kind of job that is being performed |
456273b0 | 240 | # |
26ec4e53 | 241 | # @status: Current job state/status |
456273b0 | 242 | # |
a937b6aa MA |
243 | # @current-progress: Progress made until now. The unit is arbitrary |
244 | # and the value can only meaningfully be used for the ratio of | |
245 | # @current-progress to @total-progress. The value is | |
246 | # monotonically increasing. | |
456273b0 | 247 | # |
a937b6aa MA |
248 | # @total-progress: Estimated @current-progress value at the completion |
249 | # of the job. This value can arbitrarily change while the job is | |
250 | # running, in both directions. | |
456273b0 | 251 | # |
a937b6aa MA |
252 | # @error: If this field is present, the job failed; if it is still |
253 | # missing in the CONCLUDED state, this indicates successful | |
254 | # completion. | |
456273b0 | 255 | # |
a937b6aa MA |
256 | # The value is a human-readable error message to describe the |
257 | # reason for the job failure. It should not be parsed by | |
258 | # applications. | |
456273b0 | 259 | # |
0ab1c41d | 260 | # Since: 3.0 |
456273b0 KW |
261 | ## |
262 | { 'struct': 'JobInfo', | |
263 | 'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus', | |
264 | 'current-progress': 'int', 'total-progress': 'int', | |
265 | '*error': 'str' } } | |
266 | ||
267 | ## | |
268 | # @query-jobs: | |
269 | # | |
270 | # Return information about jobs. | |
271 | # | |
272 | # Returns: a list with a @JobInfo for each active job | |
273 | # | |
0ab1c41d | 274 | # Since: 3.0 |
456273b0 KW |
275 | ## |
276 | { 'command': 'query-jobs', 'returns': ['JobInfo'] } |