]>
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 KW |
107 | # |
108 | # Since: 2.12 | |
109 | ## | |
110 | { 'enum': 'JobVerb', | |
111 | 'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss', | |
112 | 'finalize' ] } | |
1dac83f1 KW |
113 | |
114 | ## | |
115 | # @JOB_STATUS_CHANGE: | |
116 | # | |
117 | # Emitted when a job transitions to a different status. | |
118 | # | |
119 | # @id: The job identifier | |
a937b6aa | 120 | # |
1dac83f1 KW |
121 | # @status: The new job status |
122 | # | |
0ab1c41d | 123 | # Since: 3.0 |
1dac83f1 KW |
124 | ## |
125 | { 'event': 'JOB_STATUS_CHANGE', | |
126 | 'data': { 'id': 'str', | |
127 | 'status': 'JobStatus' } } | |
1a90bc81 KW |
128 | |
129 | ## | |
130 | # @job-pause: | |
131 | # | |
132 | # Pause an active job. | |
133 | # | |
a937b6aa MA |
134 | # This command returns immediately after marking the active job for |
135 | # pausing. Pausing an already paused job is an error. | |
1a90bc81 | 136 | # |
a937b6aa MA |
137 | # The job will pause as soon as possible, which means transitioning |
138 | # into the PAUSED state if it was RUNNING, or into STANDBY if it was | |
139 | # READY. The corresponding JOB_STATUS_CHANGE event will be emitted. | |
1a90bc81 KW |
140 | # |
141 | # Cancelling a paused job automatically resumes it. | |
142 | # | |
143 | # @id: The job identifier. | |
144 | # | |
0ab1c41d | 145 | # Since: 3.0 |
1a90bc81 KW |
146 | ## |
147 | { 'command': 'job-pause', 'data': { 'id': 'str' } } | |
148 | ||
149 | ## | |
150 | # @job-resume: | |
151 | # | |
152 | # Resume a paused job. | |
153 | # | |
a937b6aa MA |
154 | # This command returns immediately after resuming a paused job. |
155 | # Resuming an already running job is an error. | |
1a90bc81 | 156 | # |
91577c47 | 157 | # @id: The job identifier. |
1a90bc81 | 158 | # |
0ab1c41d | 159 | # Since: 3.0 |
1a90bc81 KW |
160 | ## |
161 | { 'command': 'job-resume', 'data': { 'id': 'str' } } | |
162 | ||
163 | ## | |
164 | # @job-cancel: | |
165 | # | |
166 | # Instruct an active background job to cancel at the next opportunity. | |
167 | # This command returns immediately after marking the active job for | |
168 | # cancellation. | |
169 | # | |
a937b6aa MA |
170 | # The job will cancel as soon as possible and then emit a |
171 | # JOB_STATUS_CHANGE event. Usually, the status will change to | |
172 | # ABORTING, but it is possible that a job successfully completes (e.g. | |
173 | # because it was almost done and there was no opportunity to cancel | |
174 | # earlier than completing the job) and transitions to PENDING instead. | |
1a90bc81 KW |
175 | # |
176 | # @id: The job identifier. | |
177 | # | |
0ab1c41d | 178 | # Since: 3.0 |
1a90bc81 KW |
179 | ## |
180 | { 'command': 'job-cancel', 'data': { 'id': 'str' } } | |
181 | ||
1a90bc81 KW |
182 | ## |
183 | # @job-complete: | |
184 | # | |
185 | # Manually trigger completion of an active job in the READY state. | |
186 | # | |
187 | # @id: The job identifier. | |
188 | # | |
0ab1c41d | 189 | # Since: 3.0 |
1a90bc81 KW |
190 | ## |
191 | { 'command': 'job-complete', 'data': { 'id': 'str' } } | |
192 | ||
193 | ## | |
194 | # @job-dismiss: | |
195 | # | |
a937b6aa MA |
196 | # Deletes a job that is in the CONCLUDED state. This command only |
197 | # needs to be run explicitly for jobs that don't have automatic | |
198 | # dismiss enabled. | |
1a90bc81 | 199 | # |
a937b6aa MA |
200 | # This command will refuse to operate on any job that has not yet |
201 | # reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that make | |
202 | # use of JOB_READY event, job-cancel or job-complete will still need | |
203 | # to be used as appropriate. | |
1a90bc81 KW |
204 | # |
205 | # @id: The job identifier. | |
206 | # | |
0ab1c41d | 207 | # Since: 3.0 |
1a90bc81 KW |
208 | ## |
209 | { 'command': 'job-dismiss', 'data': { 'id': 'str' } } | |
210 | ||
211 | ## | |
212 | # @job-finalize: | |
213 | # | |
a937b6aa MA |
214 | # Instructs all jobs in a transaction (or a single job if it is not |
215 | # part of any transaction) to finalize any graph changes and do any | |
216 | # necessary cleanup. This command requires that all involved jobs are | |
217 | # in the PENDING state. | |
1a90bc81 | 218 | # |
a937b6aa MA |
219 | # For jobs in a transaction, instructing one job to finalize will |
220 | # force ALL jobs in the transaction to finalize, so it is only | |
221 | # necessary to instruct a single member job to finalize. | |
1a90bc81 | 222 | # |
a937b6aa MA |
223 | # @id: The identifier of any job in the transaction, or of a job that |
224 | # is not part of any transaction. | |
1a90bc81 | 225 | # |
0ab1c41d | 226 | # Since: 3.0 |
1a90bc81 KW |
227 | ## |
228 | { 'command': 'job-finalize', 'data': { 'id': 'str' } } | |
456273b0 KW |
229 | |
230 | ## | |
231 | # @JobInfo: | |
232 | # | |
233 | # Information about a job. | |
234 | # | |
26ec4e53 | 235 | # @id: The job identifier |
456273b0 | 236 | # |
26ec4e53 | 237 | # @type: The kind of job that is being performed |
456273b0 | 238 | # |
26ec4e53 | 239 | # @status: Current job state/status |
456273b0 | 240 | # |
a937b6aa MA |
241 | # @current-progress: Progress made until now. The unit is arbitrary |
242 | # and the value can only meaningfully be used for the ratio of | |
243 | # @current-progress to @total-progress. The value is | |
244 | # monotonically increasing. | |
456273b0 | 245 | # |
a937b6aa MA |
246 | # @total-progress: Estimated @current-progress value at the completion |
247 | # of the job. This value can arbitrarily change while the job is | |
248 | # running, in both directions. | |
456273b0 | 249 | # |
a937b6aa MA |
250 | # @error: If this field is present, the job failed; if it is still |
251 | # missing in the CONCLUDED state, this indicates successful | |
252 | # completion. | |
456273b0 | 253 | # |
a937b6aa MA |
254 | # The value is a human-readable error message to describe the |
255 | # reason for the job failure. It should not be parsed by | |
256 | # applications. | |
456273b0 | 257 | # |
0ab1c41d | 258 | # Since: 3.0 |
456273b0 KW |
259 | ## |
260 | { 'struct': 'JobInfo', | |
261 | 'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus', | |
262 | 'current-progress': 'int', 'total-progress': 'int', | |
263 | '*error': 'str' } } | |
264 | ||
265 | ## | |
266 | # @query-jobs: | |
267 | # | |
268 | # Return information about jobs. | |
269 | # | |
270 | # Returns: a list with a @JobInfo for each active job | |
271 | # | |
0ab1c41d | 272 | # Since: 3.0 |
456273b0 KW |
273 | ## |
274 | { 'command': 'query-jobs', 'returns': ['JobInfo'] } |