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