job.json (7577B)
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## 178# @job-complete: 179# 180# Manually trigger completion of an active job in the READY state. 181# 182# @id: The job identifier. 183# 184# Since: 3.0 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# 200# Since: 3.0 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# 218# Since: 3.0 219## 220{ 'command': 'job-finalize', 'data': { 'id': 'str' } } 221 222## 223# @JobInfo: 224# 225# Information about a job. 226# 227# @id: The job identifier 228# 229# @type: The kind of job that is being performed 230# 231# @status: Current job state/status 232# 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. 237# 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. 241# 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. 245# 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. 249# 250# Since: 3.0 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# 264# Since: 3.0 265## 266{ 'command': 'query-jobs', 'returns': ['JobInfo'] }