job.json (7576B)
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 # @job-complete: 178 # 179 # Manually trigger completion of an active job in the READY state. 180 # 181 # @id: The job identifier. 182 # 183 # Since: 3.0 184 ## 185 { 'command': 'job-complete', 'data': { 'id': 'str' } } 186 187 ## 188 # @job-dismiss: 189 # 190 # Deletes a job that is in the CONCLUDED state. This command only needs to be 191 # run explicitly for jobs that don't have automatic dismiss enabled. 192 # 193 # This command will refuse to operate on any job that has not yet reached its 194 # terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of JOB_READY 195 # event, job-cancel or job-complete will still need to be used as appropriate. 196 # 197 # @id: The job identifier. 198 # 199 # Since: 3.0 200 ## 201 { 'command': 'job-dismiss', 'data': { 'id': 'str' } } 202 203 ## 204 # @job-finalize: 205 # 206 # Instructs all jobs in a transaction (or a single job if it is not part of any 207 # transaction) to finalize any graph changes and do any necessary cleanup. This 208 # command requires that all involved jobs are in the PENDING state. 209 # 210 # For jobs in a transaction, instructing one job to finalize will force 211 # ALL jobs in the transaction to finalize, so it is only necessary to instruct 212 # a single member job to finalize. 213 # 214 # @id: The identifier of any job in the transaction, or of a job that is not 215 # part of any transaction. 216 # 217 # Since: 3.0 218 ## 219 { 'command': 'job-finalize', 'data': { 'id': 'str' } } 220 221 ## 222 # @JobInfo: 223 # 224 # Information about a job. 225 # 226 # @id: The job identifier 227 # 228 # @type: The kind of job that is being performed 229 # 230 # @status: Current job state/status 231 # 232 # @current-progress: Progress made until now. The unit is arbitrary and the 233 # value can only meaningfully be used for the ratio of 234 # @current-progress to @total-progress. The value is 235 # monotonically increasing. 236 # 237 # @total-progress: Estimated @current-progress value at the completion of 238 # the job. This value can arbitrarily change while the 239 # job is running, in both directions. 240 # 241 # @error: If this field is present, the job failed; if it is 242 # still missing in the CONCLUDED state, this indicates 243 # successful completion. 244 # 245 # The value is a human-readable error message to describe 246 # the reason for the job failure. It should not be parsed 247 # by applications. 248 # 249 # Since: 3.0 250 ## 251 { 'struct': 'JobInfo', 252 'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus', 253 'current-progress': 'int', 'total-progress': 'int', 254 '*error': 'str' } } 255 256 ## 257 # @query-jobs: 258 # 259 # Return information about jobs. 260 # 261 # Returns: a list with a @JobInfo for each active job 262 # 263 # Since: 3.0 264 ## 265 { 'command': 'query-jobs', 'returns': ['JobInfo'] }