Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 1 | # -*- Mode: Python -*- |
Andrea Bolognani | f7160f3 | 2020-07-29 20:50:24 +0200 | [diff] [blame] | 2 | # vim: filetype=python |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 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 | # |
Kevin Wolf | 3fb588a | 2018-05-25 18:24:51 +0200 | [diff] [blame] | 21 | # @create: image creation job type, see "blockdev-create" (since 3.0) |
Kevin Wolf | e5ab434 | 2018-01-18 14:33:04 +0100 | [diff] [blame] | 22 | # |
Maxim Levitsky | ced914d | 2020-06-25 14:55:45 +0200 | [diff] [blame] | 23 | # @amend: image options amend job type, see "x-blockdev-amend" (since 5.1) |
| 24 | # |
Daniel P. Berrangé | 0f0d83a | 2021-02-04 12:48:34 +0000 | [diff] [blame] | 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 | # |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 31 | # Since: 1.7 |
| 32 | ## |
| 33 | { 'enum': 'JobType', |
Daniel P. Berrangé | 0f0d83a | 2021-02-04 12:48:34 +0000 | [diff] [blame] | 34 | 'data': ['commit', 'stream', 'mirror', 'backup', 'create', 'amend', |
| 35 | 'snapshot-load', 'snapshot-save', 'snapshot-delete'] } |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 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 |
John Snow | c5b09f3 | 2018-06-06 19:02:56 -0400 | [diff] [blame] | 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. |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 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 | # |
John Snow | c5b09f3 | 2018-06-06 19:02:56 -0400 | [diff] [blame] | 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. |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 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 | # |
John Snow | b8a366f | 2018-06-06 19:02:57 -0400 | [diff] [blame] | 89 | # @cancel: see @job-cancel |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 90 | # |
John Snow | b8a366f | 2018-06-06 19:02:57 -0400 | [diff] [blame] | 91 | # @pause: see @job-pause |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 92 | # |
John Snow | b8a366f | 2018-06-06 19:02:57 -0400 | [diff] [blame] | 93 | # @resume: see @job-resume |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 94 | # |
| 95 | # @set-speed: see @block-job-set-speed |
| 96 | # |
John Snow | b8a366f | 2018-06-06 19:02:57 -0400 | [diff] [blame] | 97 | # @complete: see @job-complete |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 98 | # |
John Snow | b8a366f | 2018-06-06 19:02:57 -0400 | [diff] [blame] | 99 | # @dismiss: see @job-dismiss |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 100 | # |
John Snow | b8a366f | 2018-06-06 19:02:57 -0400 | [diff] [blame] | 101 | # @finalize: see @job-finalize |
Kevin Wolf | bf42508 | 2018-05-16 16:03:10 +0200 | [diff] [blame] | 102 | # |
| 103 | # Since: 2.12 |
| 104 | ## |
| 105 | { 'enum': 'JobVerb', |
| 106 | 'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss', |
| 107 | 'finalize' ] } |
Kevin Wolf | 1dac83f | 2018-04-30 19:09:46 +0200 | [diff] [blame] | 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 | # |
Kevin Wolf | 0ab1c41 | 2018-06-26 10:37:02 +0200 | [diff] [blame] | 117 | # Since: 3.0 |
Kevin Wolf | 1dac83f | 2018-04-30 19:09:46 +0200 | [diff] [blame] | 118 | ## |
| 119 | { 'event': 'JOB_STATUS_CHANGE', |
| 120 | 'data': { 'id': 'str', |
| 121 | 'status': 'JobStatus' } } |
Kevin Wolf | 1a90bc8 | 2018-05-03 19:01:14 +0200 | [diff] [blame] | 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 | # |
Kevin Wolf | 0ab1c41 | 2018-06-26 10:37:02 +0200 | [diff] [blame] | 139 | # Since: 3.0 |
Kevin Wolf | 1a90bc8 | 2018-05-03 19:01:14 +0200 | [diff] [blame] | 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 | # |
Kevin Wolf | 0ab1c41 | 2018-06-26 10:37:02 +0200 | [diff] [blame] | 153 | # Since: 3.0 |
Kevin Wolf | 1a90bc8 | 2018-05-03 19:01:14 +0200 | [diff] [blame] | 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 | # |
Kevin Wolf | 0ab1c41 | 2018-06-26 10:37:02 +0200 | [diff] [blame] | 172 | # Since: 3.0 |
Kevin Wolf | 1a90bc8 | 2018-05-03 19:01:14 +0200 | [diff] [blame] | 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 | # |
Kevin Wolf | 0ab1c41 | 2018-06-26 10:37:02 +0200 | [diff] [blame] | 184 | # Since: 3.0 |
Kevin Wolf | 1a90bc8 | 2018-05-03 19:01:14 +0200 | [diff] [blame] | 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 | # |
Kevin Wolf | 0ab1c41 | 2018-06-26 10:37:02 +0200 | [diff] [blame] | 200 | # Since: 3.0 |
Kevin Wolf | 1a90bc8 | 2018-05-03 19:01:14 +0200 | [diff] [blame] | 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 | # |
Kevin Wolf | 0ab1c41 | 2018-06-26 10:37:02 +0200 | [diff] [blame] | 218 | # Since: 3.0 |
Kevin Wolf | 1a90bc8 | 2018-05-03 19:01:14 +0200 | [diff] [blame] | 219 | ## |
| 220 | { 'command': 'job-finalize', 'data': { 'id': 'str' } } |
Kevin Wolf | 456273b | 2018-05-04 16:25:43 +0200 | [diff] [blame] | 221 | |
| 222 | ## |
| 223 | # @JobInfo: |
| 224 | # |
| 225 | # Information about a job. |
| 226 | # |
Peter Maydell | 26ec4e5 | 2020-02-13 17:56:26 +0000 | [diff] [blame] | 227 | # @id: The job identifier |
Kevin Wolf | 456273b | 2018-05-04 16:25:43 +0200 | [diff] [blame] | 228 | # |
Peter Maydell | 26ec4e5 | 2020-02-13 17:56:26 +0000 | [diff] [blame] | 229 | # @type: The kind of job that is being performed |
Kevin Wolf | 456273b | 2018-05-04 16:25:43 +0200 | [diff] [blame] | 230 | # |
Peter Maydell | 26ec4e5 | 2020-02-13 17:56:26 +0000 | [diff] [blame] | 231 | # @status: Current job state/status |
Kevin Wolf | 456273b | 2018-05-04 16:25:43 +0200 | [diff] [blame] | 232 | # |
Peter Maydell | 26ec4e5 | 2020-02-13 17:56:26 +0000 | [diff] [blame] | 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. |
Kevin Wolf | 456273b | 2018-05-04 16:25:43 +0200 | [diff] [blame] | 237 | # |
Peter Maydell | 26ec4e5 | 2020-02-13 17:56:26 +0000 | [diff] [blame] | 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. |
Kevin Wolf | 456273b | 2018-05-04 16:25:43 +0200 | [diff] [blame] | 241 | # |
Peter Maydell | 26ec4e5 | 2020-02-13 17:56:26 +0000 | [diff] [blame] | 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. |
Kevin Wolf | 456273b | 2018-05-04 16:25:43 +0200 | [diff] [blame] | 245 | # |
Peter Maydell | 26ec4e5 | 2020-02-13 17:56:26 +0000 | [diff] [blame] | 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. |
Kevin Wolf | 456273b | 2018-05-04 16:25:43 +0200 | [diff] [blame] | 249 | # |
Kevin Wolf | 0ab1c41 | 2018-06-26 10:37:02 +0200 | [diff] [blame] | 250 | # Since: 3.0 |
Kevin Wolf | 456273b | 2018-05-04 16:25:43 +0200 | [diff] [blame] | 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 | # |
Kevin Wolf | 0ab1c41 | 2018-06-26 10:37:02 +0200 | [diff] [blame] | 264 | # Since: 3.0 |
Kevin Wolf | 456273b | 2018-05-04 16:25:43 +0200 | [diff] [blame] | 265 | ## |
| 266 | { 'command': 'query-jobs', 'returns': ['JobInfo'] } |