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