| # -*- Mode: Python -*- |
| |
| ## |
| # == Background jobs |
| ## |
| |
| ## |
| # @JobType: |
| # |
| # Type of a background job. |
| # |
| # @commit: block commit job type, see "block-commit" |
| # |
| # @stream: block stream job type, see "block-stream" |
| # |
| # @mirror: drive mirror job type, see "drive-mirror" |
| # |
| # @backup: drive backup job type, see "drive-backup" |
| # |
| # @create: image creation job type, see "blockdev-create" (since 3.0) |
| # |
| # Since: 1.7 |
| ## |
| { 'enum': 'JobType', |
| 'data': ['commit', 'stream', 'mirror', 'backup', 'create'] } |
| |
| ## |
| # @JobStatus: |
| # |
| # Indicates the present state of a given job in its lifetime. |
| # |
| # @undefined: Erroneous, default state. Should not ever be visible. |
| # |
| # @created: The job has been created, but not yet started. |
| # |
| # @running: The job is currently running. |
| # |
| # @paused: The job is running, but paused. The pause may be requested by |
| # either the QMP user or by internal processes. |
| # |
| # @ready: The job is running, but is ready for the user to signal completion. |
| # This is used for long-running jobs like mirror that are designed to |
| # run indefinitely. |
| # |
| # @standby: The job is ready, but paused. This is nearly identical to @paused. |
| # The job may return to @ready or otherwise be canceled. |
| # |
| # @waiting: The job is waiting for other jobs in the transaction to converge |
| # to the waiting state. This status will likely not be visible for |
| # the last job in a transaction. |
| # |
| # @pending: The job has finished its work, but has finalization steps that it |
| # needs to make prior to completing. These changes may require |
| # manual intervention by the management process if manual was set |
| # to true. These changes may still fail. |
| # |
| # @aborting: The job is in the process of being aborted, and will finish with |
| # an error. The job will afterwards report that it is @concluded. |
| # This status may not be visible to the management process. |
| # |
| # @concluded: The job has finished all work. If manual was set to true, the job |
| # will remain in the query list until it is dismissed. |
| # |
| # @null: The job is in the process of being dismantled. This state should not |
| # ever be visible externally. |
| # |
| # Since: 2.12 |
| ## |
| { 'enum': 'JobStatus', |
| 'data': ['undefined', 'created', 'running', 'paused', 'ready', 'standby', |
| 'waiting', 'pending', 'aborting', 'concluded', 'null' ] } |
| |
| ## |
| # @JobVerb: |
| # |
| # Represents command verbs that can be applied to a job. |
| # |
| # @cancel: see @block-job-cancel |
| # |
| # @pause: see @block-job-pause |
| # |
| # @resume: see @block-job-resume |
| # |
| # @set-speed: see @block-job-set-speed |
| # |
| # @complete: see @block-job-complete |
| # |
| # @dismiss: see @block-job-dismiss |
| # |
| # @finalize: see @block-job-finalize |
| # |
| # Since: 2.12 |
| ## |
| { 'enum': 'JobVerb', |
| 'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss', |
| 'finalize' ] } |
| |
| ## |
| # @JOB_STATUS_CHANGE: |
| # |
| # Emitted when a job transitions to a different status. |
| # |
| # @id: The job identifier |
| # @status: The new job status |
| # |
| # Since: 2.13 |
| ## |
| { 'event': 'JOB_STATUS_CHANGE', |
| 'data': { 'id': 'str', |
| 'status': 'JobStatus' } } |
| |
| ## |
| # @job-pause: |
| # |
| # Pause an active job. |
| # |
| # This command returns immediately after marking the active job for pausing. |
| # Pausing an already paused job is an error. |
| # |
| # The job will pause as soon as possible, which means transitioning into the |
| # PAUSED state if it was RUNNING, or into STANDBY if it was READY. The |
| # corresponding JOB_STATUS_CHANGE event will be emitted. |
| # |
| # Cancelling a paused job automatically resumes it. |
| # |
| # @id: The job identifier. |
| # |
| # Since: 2.13 |
| ## |
| { 'command': 'job-pause', 'data': { 'id': 'str' } } |
| |
| ## |
| # @job-resume: |
| # |
| # Resume a paused job. |
| # |
| # This command returns immediately after resuming a paused job. Resuming an |
| # already running job is an error. |
| # |
| # @id : The job identifier. |
| # |
| # Since: 2.13 |
| ## |
| { 'command': 'job-resume', 'data': { 'id': 'str' } } |
| |
| ## |
| # @job-cancel: |
| # |
| # Instruct an active background job to cancel at the next opportunity. |
| # This command returns immediately after marking the active job for |
| # cancellation. |
| # |
| # The job will cancel as soon as possible and then emit a JOB_STATUS_CHANGE |
| # event. Usually, the status will change to ABORTING, but it is possible that |
| # a job successfully completes (e.g. because it was almost done and there was |
| # no opportunity to cancel earlier than completing the job) and transitions to |
| # PENDING instead. |
| # |
| # @id: The job identifier. |
| # |
| # Since: 2.13 |
| ## |
| { 'command': 'job-cancel', 'data': { 'id': 'str' } } |
| |
| |
| ## |
| # @job-complete: |
| # |
| # Manually trigger completion of an active job in the READY state. |
| # |
| # @id: The job identifier. |
| # |
| # Since: 2.13 |
| ## |
| { 'command': 'job-complete', 'data': { 'id': 'str' } } |
| |
| ## |
| # @job-dismiss: |
| # |
| # Deletes a job that is in the CONCLUDED state. This command only needs to be |
| # run explicitly for jobs that don't have automatic dismiss enabled. |
| # |
| # This command will refuse to operate on any job that has not yet reached its |
| # terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of JOB_READY |
| # event, job-cancel or job-complete will still need to be used as appropriate. |
| # |
| # @id: The job identifier. |
| # |
| # Since: 2.13 |
| ## |
| { 'command': 'job-dismiss', 'data': { 'id': 'str' } } |
| |
| ## |
| # @job-finalize: |
| # |
| # Instructs all jobs in a transaction (or a single job if it is not part of any |
| # transaction) to finalize any graph changes and do any necessary cleanup. This |
| # command requires that all involved jobs are in the PENDING state. |
| # |
| # For jobs in a transaction, instructing one job to finalize will force |
| # ALL jobs in the transaction to finalize, so it is only necessary to instruct |
| # a single member job to finalize. |
| # |
| # @id: The identifier of any job in the transaction, or of a job that is not |
| # part of any transaction. |
| # |
| # Since: 2.13 |
| ## |
| { 'command': 'job-finalize', 'data': { 'id': 'str' } } |
| |
| ## |
| # @JobInfo: |
| # |
| # Information about a job. |
| # |
| # @id: The job identifier |
| # |
| # @type: The kind of job that is being performed |
| # |
| # @status: Current job state/status |
| # |
| # @current-progress: Progress made until now. The unit is arbitrary and the |
| # value can only meaningfully be used for the ratio of |
| # @current-progress to @total-progress. The value is |
| # monotonically increasing. |
| # |
| # @total-progress: Estimated @current-progress value at the completion of |
| # the job. This value can arbitrarily change while the |
| # job is running, in both directions. |
| # |
| # @error: If this field is present, the job failed; if it is |
| # still missing in the CONCLUDED state, this indicates |
| # successful completion. |
| # |
| # The value is a human-readable error message to describe |
| # the reason for the job failure. It should not be parsed |
| # by applications. |
| # |
| # Since: 2.13 |
| ## |
| { 'struct': 'JobInfo', |
| 'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus', |
| 'current-progress': 'int', 'total-progress': 'int', |
| '*error': 'str' } } |
| |
| ## |
| # @query-jobs: |
| # |
| # Return information about jobs. |
| # |
| # Returns: a list with a @JobInfo for each active job |
| # |
| # Since: 2.13 |
| ## |
| { 'command': 'query-jobs', 'returns': ['JobInfo'] } |