29 #include "qapi/qapi-types-job.h"
42 typedef struct Job {  struct
46     /** The ID of the job. May be NULL for internal jobs. */
50      * The type of this job.
56      * The coroutine that executes the job.  If not NULL, it is reentered when
57      * busy is false and the job is cancelled.
62     /** True if this job should automatically finalize itself */
65     /** True if this job should automatically dismiss itself */
69      * The completion function that will be called when the job completes.
80      * AioContext to run the job coroutine in.
81      * The job Aiocontext can be read when holding *either*
91     /** Reference count of the block job */
99      * job.c).
104      * Counter for pause request. If non-zero, the block job is either paused,
110      * Set to false by the job while the coroutine has yielded and may be
114      * When the job is deferred to the main loop, busy is true as long as the
120      * Set to true by the job while it is in a quiescent state, where
126      * Set to true if the job is paused by user.  Can be unpaused with the
127      * block-job-resume QMP command.
132      * Set to true if the job should cancel itself.  The flag must
134      * to true.  After a job has been cancelled, it should only yield
140      * Set to true if the job should abort immediately without waiting
145     /** Set to true when the job has deferred work to the main loop. */
150      * Not final until the job has reached the CONCLUDED status.
156      * Error object for a failed job.
157      * If job->ret is nonzero and an error object was not set, it will be set
158      * to strerror(-job->ret) during job_completed.
162     /** Notifiers called when a cancelled job is finalised */
165     /** Notifiers called when a successfully completed job is finalised */
168     /** Notifiers called when the job transitions to PENDING */
171     /** Notifiers called when the job transitions to READY */
174     /** Notifiers called when the job coroutine yields or terminates */
178     QLIST_ENTRY(Job) job_list;  argument
180     /** Transaction this job is part of */
183     /** Element of the list of jobs in a job transaction */
184     QLIST_ENTRY(Job) txn_list;
185 } Job;  typedef
188  * Callbacks and other information about a Job driver.
198     /** Derived Job struct size */
209      * If this callback returns nonzero, the job transaction it is part of is
210      * aborted. If it returns zero, the job moves into the WAITING state. If it
211      * is the last job to complete in its transaction, all jobs in the
214      * This callback must be run in the job's context.
216     int coroutine_fn (*run)(Job *job, Error **errp);
226      * If the callback is not NULL, it will be invoked when the job transitions
230     void coroutine_fn (*pause)(Job *job);
233      * If the callback is not NULL, it will be invoked when the job transitions
237     void coroutine_fn (*resume)(Job *job);
247      * Called when the job is resumed by the user (i.e. user_paused becomes
250     void (*user_resume)(Job *job);
253      * Optional callback for job types whose completion must be triggered
256     void (*complete)(Job *job, Error **errp);
260      * belonging to the same transaction complete; or upon this job's completion
263      * This callback will not be invoked if the job has already failed.
266     int (*prepare)(Job *job);
270      * belonging to the same transaction complete; or upon this job's
276     void (*commit)(Job *job);
279      * If the callback is not NULL, it will be invoked when any job in the
280      * same transaction fails; or upon this job's failure (due to error or
286     void (*abort)(Job *job);
291      * completion, .clean() will always be called, even if the job does not
294     void (*clean)(Job *job);
299      * This function must return true if the job will be cancelled
301      * true), and false otherwise.  This lets the generic job layer
302      * know whether a job has been truly (force-)cancelled, or whether
305      * (If the callback is NULL, the job is assumed to terminate
308     bool (*cancel)(Job *job, bool force);
312      * Called when the job is freed.
314     void (*free)(Job *job);
320     /* Job is not QMP-created and should not send QMP events */
322     /* Job requires manual finalize step */
324     /* Job requires manual dismiss step */
353  * Allocate and return a new job transaction. Jobs can be added to the
356  * The transaction is automatically freed when the last job completes or is
360  * group.  Jobs wait for each other before completing.  Cancelling one job
369  * Called with job lock *not* held.
374  * Same as job_txn_unref(), but called with job lock held.
380  * Create a new long-running job and return it.
383  * @job_id: The id of the newly-created job, or %NULL for internal jobs
384  * @driver: The class object for the newly-created job.
385  * @txn: The transaction this job belongs to, if any. %NULL otherwise.
386  * @ctx: The AioContext to run the job coroutine in.
387  * @flags: Creation flags for the job. See @JobCreateFlags.
388  * @cb: Completion function for the job.
397  * Add a reference to Job refcnt, it will be decreased with job_unref, and then
400  * Called with job lock held.
402 void job_ref_locked(Job *job);
408  * Called with job lock held.
410 void job_unref_locked(Job *job);
413  * @job: The job that has made progress
414  * @done: How much progress the job made since the last call
416  * Updates the progress counter of the job.
420 void job_progress_update(Job *job, uint64_t done);
423  * @job: The job whose expected progress end value is set
427  * Sets the expected end value of the progress counter of a job so that a
432 void job_progress_set_remaining(Job *job, uint64_t remaining);
435  * @job: The job whose expected progress end value is updated
439  * Increases the expected end value of the progress counter of a job.
440  * This is useful for parenthesis operations: If a job has to
444  * (So the operation acts as a parenthesis in regards to the main job
449 void job_progress_increase_remaining(Job *job, uint64_t delta);
452  * Conditionally enter the job coroutine if the job is ready to run, not
456  * Called with job lock held, but might release it temporarily.
458 void job_enter_cond_locked(Job *job, bool(*fn)(Job *job));
461  * @job: A job that has not yet been started.
463  * Begins execution of a job.
464  * Takes ownership of one reference to the job object.
468 void job_start(Job *job);
471  * @job: The job to enter.
473  * Continue the specified job by entering the coroutine.
476 void job_enter(Job *job);
479  * @job: The job that is ready to pause.
482  * must call this between requests so that the job can be paused.
486 void coroutine_fn GRAPH_UNLOCKED job_pause_point(Job *job);
489  * @job: The job that calls the function.
491  * Yield the job coroutine.
494 void coroutine_fn job_yield(Job *job);
497  * @job: The job that calls the function.
500  * Put the job to sleep (assuming that it wasn't canceled) for @ns
501  * %QEMU_CLOCK_REALTIME nanoseconds.  Canceling the job will immediately
506 void coroutine_fn job_sleep_ns(Job *job, int64_t ns);
508 /** Returns the JobType of a given Job. */
509 JobType job_type(const Job *job);
511 /** Returns the enum string for the JobType of a given Job. */
512 const char *job_type_str(const Job *job);
514 /** Returns true if the job should not be visible to the management layer. */
515 bool job_is_internal(Job *job);
518  * Returns whether the job is being cancelled.
521 bool job_is_cancelled(Job *job);
523 /* Same as job_is_cancelled(), but called with job lock held. */
524 bool job_is_cancelled_locked(Job *job);
527  * Returns whether the job is scheduled for cancellation (at an
531 bool job_cancel_requested(Job *job);
534  * Returns whether the job is in a completed state.
535  * Called with job lock held.
537 bool job_is_completed_locked(Job *job);
540  * Returns whether the job is ready to be completed.
543 bool job_is_ready(Job *job);
545 /* Same as job_is_ready(), but called with job lock held. */
546 bool job_is_ready_locked(Job *job);
549  * Request @job to pause at the next pause point. Must be paired with
550  * job_resume(). If the job is supposed to be resumed by user action, call
553  * Called with job lock *not* held.
555 void job_pause(Job *job);
557 /* Same as job_pause(), but called with job lock held. */
558 void job_pause_locked(Job *job);
560 /** Resumes a @job paused with job_pause. Called with job lock *not* held. */
561 void job_resume(Job *job);
564  * Same as job_resume(), but called with job lock held.
567 void job_resume_locked(Job *job);
570  * Asynchronously pause the specified @job.
572  * Called with job lock held.
574 void job_user_pause_locked(Job *job, Error **errp);
577  * Returns true if the job is user-paused.
578  * Called with job lock held.
580 bool job_user_paused_locked(Job *job);
583  * Resume the specified @job.
585  * Called with job lock held, but might release it temporarily.
587 void job_user_resume_locked(Job *job, Error **errp);
590  * Get the next element from the list of block jobs after @job, or the
591  * first one if @job is %NULL.
593  * Returns the requested job, or %NULL if there are no more jobs left.
594  * Called with job lock *not* held.
596 Job *job_next(Job *job);
598 /* Same as job_next(), but called with job lock held. */
599 Job *job_next_locked(Job *job);
602  * Get the job identified by @id (which must not be %NULL).
604  * Returns the requested job, or %NULL if it doesn't exist.
605  * Called with job lock held.
607 Job *job_get_locked(const char *id);
610  * Check whether the verb @verb can be applied to @job in its current state.
614  * Called with job lock held.
616 int job_apply_verb_locked(Job *job, JobVerb verb, Error **errp);
619  * The @job could not be started, free it.
622 void job_early_fail(Job *job);
625  * Moves the @job from RUNNING to READY.
628 void job_transition_to_ready(Job *job);
631  * Asynchronously complete the specified @job.
632  * Called with job lock held, but might release it temporarily.
634 void job_complete_locked(Job *job, Error **errp);
637  * Asynchronously cancel the specified @job. If @force is true, the job should
639  * Called with job lock held.
641 void job_cancel_locked(Job *job, bool force);
644  * Cancels the specified job like job_cancel_locked(), but may refuse
645  * to do so if the operation isn't meaningful in the current state of the job.
646  * Called with job lock held.
648 void job_user_cancel_locked(Job *job, bool force, Error **errp);
651  * Synchronously cancel the @job.  The completion callback is called
652  * before the function returns.  If @force is false, the job may
654  * under which this happens depend on the kind of job that is active.
656  * Returns the return value from the job if the job actually completed
661 int job_cancel_sync(Job *job, bool force);
663 /* Same as job_cancel_sync, but called with job lock held. */
664 int job_cancel_sync_locked(Job *job, bool force);
674  * @job: The job to be completed.
676  *        necessarily set on every error, the job return value has to be
679  * Synchronously complete the job.  The completion callback is called before the
683  * Returns the return value from the job.
686 int job_complete_sync_locked(Job *job, Error **errp);
689  * For a @job that has finished its work and is pending awaiting explicit
696  * Called with job lock held.
698 void job_finalize_locked(Job *job, Error **errp);
701  * Remove the concluded @job from the query list and resets the passed pointer
702  * to %NULL. Returns an error if the job is not actually concluded.
704  * Called with job lock held.
706 void job_dismiss_locked(Job **job, Error **errp);
709  * Synchronously finishes the given @job. If @finish is given, it is called to
710  * trigger completion or cancellation of the job.
712  * Returns 0 if the job is successfully completed, -ECANCELED if the job was
717 int job_finish_sync_locked(Job *job, void (*finish)(Job *, Error **errp),
721  * Sets the @job->aio_context.
727  * be called when the job is quiescent.
729 void job_set_aio_context(Job *job, AioContext *ctx);