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