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