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