qapi/job.json

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