qapi/job.json

   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
  24 #     5.1)
  25 #
  26 # @snapshot-load: snapshot load job type, see "snapshot-load" (since
  27 #     6.0)
  28 #
  29 # @snapshot-save: snapshot save job type, see "snapshot-save" (since
  30 #     6.0)
  31 #
  32 # @snapshot-delete: snapshot delete job type, see "snapshot-delete"
  33 #     (since 6.0)
  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 #
  46 # @undefined: Erroneous, default state.  Should not ever be visible.
  47 #
  48 # @created: The job has been created, but not yet started.
  49 #
  50 # @running: The job is currently running.
  51 #
  52 # @paused: The job is running, but paused.  The pause may be requested
  53 #     by either the QMP user or by internal processes.
  54 #
  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.
  58 #
  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.
  61 #
  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.
  65 #
  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.
  70 #
  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.
  75 #
  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.
  79 #
  80 # @null: The job is in the process of being dismantled.  This state
  81 #     should not ever be visible externally.
  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 ##
  90 # @JobVerb:
  91 #
  92 # Represents command verbs that can be applied to a job.
  93 #
  94 # @cancel: see @job-cancel
  95 #
  96 # @pause: see @job-pause
  97 #
  98 # @resume: see @job-resume
  99 #
 100 # @set-speed: see @block-job-set-speed
 101 #
 102 # @complete: see @job-complete
 103 #
 104 # @dismiss: see @job-dismiss
 105 #
 106 # @finalize: see @job-finalize
 107 #
 108 # @change: see @block-job-change (since 8.2)
 109 #
 110 # Since: 2.12
 111 ##
 112 { 'enum': 'JobVerb',
 113   'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
 114            'finalize', 'change' ] }
 115
 116 ##
 117 # @JOB_STATUS_CHANGE:
 118 #
 119 # Emitted when a job transitions to a different status.
 120 #
 121 # @id: The job identifier
 122 #
 123 # @status: The new job status
 124 #
 125 # Since: 3.0
 126 ##
 127 { 'event': 'JOB_STATUS_CHANGE',
 128   'data': { 'id': 'str',
 129             'status': 'JobStatus' } }
 130
 131 ##
 132 # @job-pause:
 133 #
 134 # Pause an active job.
 135 #
 136 # This command returns immediately after marking the active job for
 137 # pausing.  Pausing an already paused job is an error.
 138 #
 139 # The job will pause as soon as possible, which means transitioning
 140 # into the PAUSED state if it was RUNNING, or into STANDBY if it was
 141 # READY. The corresponding JOB_STATUS_CHANGE event will be emitted.
 142 #
 143 # Cancelling a paused job automatically resumes it.
 144 #
 145 # @id: The job identifier.
 146 #
 147 # Since: 3.0
 148 ##
 149 { 'command': 'job-pause', 'data': { 'id': 'str' } }
 150
 151 ##
 152 # @job-resume:
 153 #
 154 # Resume a paused job.
 155 #
 156 # This command returns immediately after resuming a paused job.
 157 # Resuming an already running job is an error.
 158 #
 159 # @id: The job identifier.
 160 #
 161 # Since: 3.0
 162 ##
 163 { 'command': 'job-resume', 'data': { 'id': 'str' } }
 164
 165 ##
 166 # @job-cancel:
 167 #
 168 # Instruct an active background job to cancel at the next opportunity.
 169 # This command returns immediately after marking the active job for
 170 # cancellation.
 171 #
 172 # The job will cancel as soon as possible and then emit a
 173 # JOB_STATUS_CHANGE event.  Usually, the status will change to
 174 # ABORTING, but it is possible that a job successfully completes (e.g.
 175 # because it was almost done and there was no opportunity to cancel
 176 # earlier than completing the job) and transitions to PENDING instead.
 177 #
 178 # @id: The job identifier.
 179 #
 180 # Since: 3.0
 181 ##
 182 { 'command': 'job-cancel', 'data': { 'id': 'str' } }
 183
 184 ##
 185 # @job-complete:
 186 #
 187 # Manually trigger completion of an active job in the READY state.
 188 #
 189 # @id: The job identifier.
 190 #
 191 # Since: 3.0
 192 ##
 193 { 'command': 'job-complete', 'data': { 'id': 'str' } }
 194
 195 ##
 196 # @job-dismiss:
 197 #
 198 # Deletes a job that is in the CONCLUDED state.  This command only
 199 # needs to be run explicitly for jobs that don't have automatic
 200 # dismiss enabled.
 201 #
 202 # This command will refuse to operate on any job that has not yet
 203 # reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that make
 204 # use of JOB_READY event, job-cancel or job-complete will still need
 205 # to be used as appropriate.
 206 #
 207 # @id: The job identifier.
 208 #
 209 # Since: 3.0
 210 ##
 211 { 'command': 'job-dismiss', 'data': { 'id': 'str' } }
 212
 213 ##
 214 # @job-finalize:
 215 #
 216 # Instructs all jobs in a transaction (or a single job if it is not
 217 # part of any transaction) to finalize any graph changes and do any
 218 # necessary cleanup.  This command requires that all involved jobs are
 219 # in the PENDING state.
 220 #
 221 # For jobs in a transaction, instructing one job to finalize will
 222 # force ALL jobs in the transaction to finalize, so it is only
 223 # necessary to instruct a single member job to finalize.
 224 #
 225 # @id: The identifier of any job in the transaction, or of a job that
 226 #     is not part of any transaction.
 227 #
 228 # Since: 3.0
 229 ##
 230 { 'command': 'job-finalize', 'data': { 'id': 'str' } }
 231
 232 ##
 233 # @JobInfo:
 234 #
 235 # Information about a job.
 236 #
 237 # @id: The job identifier
 238 #
 239 # @type: The kind of job that is being performed
 240 #
 241 # @status: Current job state/status
 242 #
 243 # @current-progress: Progress made until now.  The unit is arbitrary
 244 #     and the value can only meaningfully be used for the ratio of
 245 #     @current-progress to @total-progress.  The value is
 246 #     monotonically increasing.
 247 #
 248 # @total-progress: Estimated @current-progress value at the completion
 249 #     of the job.  This value can arbitrarily change while the job is
 250 #     running, in both directions.
 251 #
 252 # @error: If this field is present, the job failed; if it is still
 253 #     missing in the CONCLUDED state, this indicates successful
 254 #     completion.
 255 #
 256 #     The value is a human-readable error message to describe the
 257 #     reason for the job failure.  It should not be parsed by
 258 #     applications.
 259 #
 260 # Since: 3.0
 261 ##
 262 { 'struct': 'JobInfo',
 263   'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus',
 264             'current-progress': 'int', 'total-progress': 'int',
 265             '*error': 'str' } }
 266
 267 ##
 268 # @query-jobs:
 269 #
 270 # Return information about jobs.
 271 #
 272 # Returns: a list with a @JobInfo for each active job
 273 #
 274 # Since: 3.0
 275 ##
 276 { 'command': 'query-jobs', 'returns': ['JobInfo'] }