Merge remote-tracking branch 'remotes/vivier2/tags/linux-user-for-6.2-pull-request...
[qemu.git] / qapi / job.json
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3
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 #
21 # @create: image creation job type, see "blockdev-create" (since 3.0)
22 #
23 # @amend: image options amend job type, see "x-blockdev-amend" (since 5.1)
24 #
25 # @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 #
31 # Since: 1.7
32 ##
33 { 'enum': 'JobType',
34   'data': ['commit', 'stream', 'mirror', 'backup', 'create', 'amend',
35            'snapshot-load', 'snapshot-save', 'snapshot-delete'] }
36
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
63 #           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.
66 #
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 #
71 # @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.
74 #
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 #
89 # @cancel: see @job-cancel
90 #
91 # @pause: see @job-pause
92 #
93 # @resume: see @job-resume
94 #
95 # @set-speed: see @block-job-set-speed
96 #
97 # @complete: see @job-complete
98 #
99 # @dismiss: see @job-dismiss
100 #
101 # @finalize: see @job-finalize
102 #
103 # Since: 2.12
104 ##
105 { 'enum': 'JobVerb',
106   'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
107            'finalize' ] }
108
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 #
117 # Since: 3.0
118 ##
119 { 'event': 'JOB_STATUS_CHANGE',
120   'data': { 'id': 'str',
121             'status': 'JobStatus' } }
122
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 #
139 # Since: 3.0
140 ##
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 #
153 # Since: 3.0
154 ##
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 #
172 # Since: 3.0
173 ##
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 #
184 # Since: 3.0
185 ##
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 #
200 # Since: 3.0
201 ##
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 #
218 # Since: 3.0
219 ##
220 { 'command': 'job-finalize', 'data': { 'id': 'str' } }
221
222 ##
223 # @JobInfo:
224 #
225 # Information about a job.
226 #
227 # @id: The job identifier
228 #
229 # @type: The kind of job that is being performed
230 #
231 # @status: Current job state/status
232 #
233 # @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.
237 #
238 # @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.
241 #
242 # @error: If this field is present, the job failed; if it is
243 #         still missing in the CONCLUDED state, this indicates
244 #         successful completion.
245 #
246 #         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.
249 #
250 # Since: 3.0
251 ##
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 #
264 # Since: 3.0
265 ##
266 { 'command': 'query-jobs', 'returns': ['JobInfo'] }