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 # Since: 2.12
 109 ##
 110 { 'enum': 'JobVerb',
 111   'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
 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 #
 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 #
 134 # This command returns immediately after marking the active job for
 135 # pausing.  Pausing an already paused job is an error.
 136 #
 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.
 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 #
 154 # This command returns immediately after resuming a paused job.
 155 # Resuming an already running job is an error.
 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 #
 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.
 175 #
 176 # @id: The job identifier.
 177 #
 178 # Since: 3.0
 179 ##
 180 { 'command': 'job-cancel', 'data': { 'id': 'str' } }
 181
 182 ##
 183 # @job-complete:
 184 #
 185 # Manually trigger completion of an active job in the READY state.
 186 #
 187 # @id: The job identifier.
 188 #
 189 # Since: 3.0
 190 ##
 191 { 'command': 'job-complete', 'data': { 'id': 'str' } }
 192
 193 ##
 194 # @job-dismiss:
 195 #
 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.
 199 #
 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.
 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 #
 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.
 218 #
 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.
 222 #
 223 # @id: The identifier of any job in the transaction, or of a job that
 224 #     is not part of any transaction.
 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 #
 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.
 245 #
 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.
 249 #
 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.
 253 #
 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.
 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'] }