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 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'] }