xref: /openbmc/qemu/include/qemu/job.h (revision ae5a40e8)
1 /*
2  * Declarations for background jobs
3  *
4  * Copyright (c) 2011 IBM Corp.
5  * Copyright (c) 2012, 2018 Red Hat, Inc.
6  *
7  * Permission is hereby granted, free of charge, to any person obtaining a copy
8  * of this software and associated documentation files (the "Software"), to deal
9  * in the Software without restriction, including without limitation the rights
10  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11  * copies of the Software, and to permit persons to whom the Software is
12  * furnished to do so, subject to the following conditions:
13  *
14  * The above copyright notice and this permission notice shall be included in
15  * all copies or substantial portions of the Software.
16  *
17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
20  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
23  * THE SOFTWARE.
24  */
25 
26 #ifndef JOB_H
27 #define JOB_H
28 
29 #include "qapi/qapi-types-job.h"
30 #include "qemu/queue.h"
31 #include "qemu/progress_meter.h"
32 #include "qemu/coroutine.h"
33 #include "block/aio.h"
34 
35 typedef struct JobDriver JobDriver;
36 typedef struct JobTxn JobTxn;
37 
38 
39 /**
40  * Long-running operation.
41  */
42 typedef struct Job {
43 
44     /* Fields set at initialization (job_create), and never modified */
45 
46     /** The ID of the job. May be NULL for internal jobs. */
47     char *id;
48 
49     /**
50      * The type of this job.
51      * All callbacks are called with job_mutex *not* held.
52      */
53     const JobDriver *driver;
54 
55     /**
56      * The coroutine that executes the job.  If not NULL, it is reentered when
57      * busy is false and the job is cancelled.
58      * Initialized in job_start()
59      */
60     Coroutine *co;
61 
62     /** True if this job should automatically finalize itself */
63     bool auto_finalize;
64 
65     /** True if this job should automatically dismiss itself */
66     bool auto_dismiss;
67 
68     /**
69      * The completion function that will be called when the job completes.
70      */
71     BlockCompletionFunc *cb;
72 
73     /** The opaque value that is passed to the completion function.  */
74     void *opaque;
75 
76     /* ProgressMeter API is thread-safe */
77     ProgressMeter progress;
78 
79     /**
80      * AioContext to run the job coroutine in.
81      * The job Aiocontext can be read when holding *either*
82      * the BQL (so we are in the main loop) or the job_mutex.
83      * It can only be written when we hold *both* BQL
84      * and the job_mutex.
85      */
86     AioContext *aio_context;
87 
88 
89     /** Protected by job_mutex */
90 
91     /** Reference count of the block job */
92     int refcnt;
93 
94     /** Current state; See @JobStatus for details. */
95     JobStatus status;
96 
97     /**
98      * Timer that is used by @job_sleep_ns. Accessed under job_mutex (in
99      * job.c).
100      */
101     QEMUTimer sleep_timer;
102 
103     /**
104      * Counter for pause request. If non-zero, the block job is either paused,
105      * or if busy == true will pause itself as soon as possible.
106      */
107     int pause_count;
108 
109     /**
110      * Set to false by the job while the coroutine has yielded and may be
111      * re-entered by job_enter(). There may still be I/O or event loop activity
112      * pending. Accessed under job_mutex.
113      *
114      * When the job is deferred to the main loop, busy is true as long as the
115      * bottom half is still pending.
116      */
117     bool busy;
118 
119     /**
120      * Set to true by the job while it is in a quiescent state, where
121      * no I/O or event loop activity is pending.
122      */
123     bool paused;
124 
125     /**
126      * Set to true if the job is paused by user.  Can be unpaused with the
127      * block-job-resume QMP command.
128      */
129     bool user_paused;
130 
131     /**
132      * Set to true if the job should cancel itself.  The flag must
133      * always be tested just before toggling the busy flag from false
134      * to true.  After a job has been cancelled, it should only yield
135      * if #aio_poll will ("sooner or later") reenter the coroutine.
136      */
137     bool cancelled;
138 
139     /**
140      * Set to true if the job should abort immediately without waiting
141      * for data to be in sync.
142      */
143     bool force_cancel;
144 
145     /** Set to true when the job has deferred work to the main loop. */
146     bool deferred_to_main_loop;
147 
148     /**
149      * Return code from @run and/or @prepare callback(s).
150      * Not final until the job has reached the CONCLUDED status.
151      * 0 on success, -errno on failure.
152      */
153     int ret;
154 
155     /**
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.
159      */
160     Error *err;
161 
162     /** Notifiers called when a cancelled job is finalised */
163     NotifierList on_finalize_cancelled;
164 
165     /** Notifiers called when a successfully completed job is finalised */
166     NotifierList on_finalize_completed;
167 
168     /** Notifiers called when the job transitions to PENDING */
169     NotifierList on_pending;
170 
171     /** Notifiers called when the job transitions to READY */
172     NotifierList on_ready;
173 
174     /** Notifiers called when the job coroutine yields or terminates */
175     NotifierList on_idle;
176 
177     /** Element of the list of jobs */
178     QLIST_ENTRY(Job) job_list;
179 
180     /** Transaction this job is part of */
181     JobTxn *txn;
182 
183     /** Element of the list of jobs in a job transaction */
184     QLIST_ENTRY(Job) txn_list;
185 } Job;
186 
187 /**
188  * Callbacks and other information about a Job driver.
189  * All callbacks are invoked with job_mutex *not* held.
190  */
191 struct JobDriver {
192 
193     /*
194      * These fields are initialized when this object is created,
195      * and are never changed afterwards
196      */
197 
198     /** Derived Job struct size */
199     size_t instance_size;
200 
201     /** Enum describing the operation */
202     JobType job_type;
203 
204     /**
205      * Mandatory: Entrypoint for the Coroutine.
206      *
207      * This callback will be invoked when moving from CREATED to RUNNING.
208      *
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
212      * transaction move from WAITING to PENDING.
213      *
214      * This callback must be run in the job's context.
215      */
216     int coroutine_fn (*run)(Job *job, Error **errp);
217 
218     /*
219      * Functions run without regard to the BQL that may run in any
220      * arbitrary thread. These functions do not need to be thread-safe
221      * because the caller ensures that they are invoked from one
222      * thread at time.
223      */
224 
225     /**
226      * If the callback is not NULL, it will be invoked when the job transitions
227      * into the paused state.  Paused jobs must not perform any asynchronous
228      * I/O or event loop activity.  This callback is used to quiesce jobs.
229      */
230     void coroutine_fn (*pause)(Job *job);
231 
232     /**
233      * If the callback is not NULL, it will be invoked when the job transitions
234      * out of the paused state.  Any asynchronous I/O or event loop activity
235      * should be restarted from this callback.
236      */
237     void coroutine_fn (*resume)(Job *job);
238 
239     /*
240      * Global state (GS) API. These functions run under the BQL.
241      *
242      * See include/block/block-global-state.h for more information about
243      * the GS API.
244      */
245 
246     /**
247      * Called when the job is resumed by the user (i.e. user_paused becomes
248      * false). .user_resume is called before .resume.
249      */
250     void (*user_resume)(Job *job);
251 
252     /**
253      * Optional callback for job types whose completion must be triggered
254      * manually.
255      */
256     void (*complete)(Job *job, Error **errp);
257 
258     /**
259      * If the callback is not NULL, prepare will be invoked when all the jobs
260      * belonging to the same transaction complete; or upon this job's completion
261      * if it is not in a transaction.
262      *
263      * This callback will not be invoked if the job has already failed.
264      * If it fails, abort and then clean will be called.
265      */
266     int (*prepare)(Job *job);
267 
268     /**
269      * If the callback is not NULL, it will be invoked when all the jobs
270      * belonging to the same transaction complete; or upon this job's
271      * completion if it is not in a transaction. Skipped if NULL.
272      *
273      * All jobs will complete with a call to either .commit() or .abort() but
274      * never both.
275      */
276     void (*commit)(Job *job);
277 
278     /**
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
281      * cancellation) if it is not in a transaction. Skipped if NULL.
282      *
283      * All jobs will complete with a call to either .commit() or .abort() but
284      * never both.
285      */
286     void (*abort)(Job *job);
287 
288     /**
289      * If the callback is not NULL, it will be invoked after a call to either
290      * .commit() or .abort(). Regardless of which callback is invoked after
291      * completion, .clean() will always be called, even if the job does not
292      * belong to a transaction group.
293      */
294     void (*clean)(Job *job);
295 
296     /**
297      * If the callback is not NULL, it will be invoked in job_cancel_async
298      *
299      * This function must return true if the job will be cancelled
300      * immediately without any further I/O (mandatory if @force is
301      * true), and false otherwise.  This lets the generic job layer
302      * know whether a job has been truly (force-)cancelled, or whether
303      * it is just in a special completion mode (like mirror after
304      * READY).
305      * (If the callback is NULL, the job is assumed to terminate
306      * without I/O.)
307      */
308     bool (*cancel)(Job *job, bool force);
309 
310 
311     /**
312      * Called when the job is freed.
313      */
314     void (*free)(Job *job);
315 };
316 
317 typedef enum JobCreateFlags {
318     /* Default behavior */
319     JOB_DEFAULT = 0x00,
320     /* Job is not QMP-created and should not send QMP events */
321     JOB_INTERNAL = 0x01,
322     /* Job requires manual finalize step */
323     JOB_MANUAL_FINALIZE = 0x02,
324     /* Job requires manual dismiss step */
325     JOB_MANUAL_DISMISS = 0x04,
326 } JobCreateFlags;
327 
328 extern QemuMutex job_mutex;
329 
330 #define JOB_LOCK_GUARD() QEMU_LOCK_GUARD(&job_mutex)
331 
332 #define WITH_JOB_LOCK_GUARD() WITH_QEMU_LOCK_GUARD(&job_mutex)
333 
334 /**
335  * job_lock:
336  *
337  * Take the mutex protecting the list of jobs and their status.
338  * Most functions called by the monitor need to call job_lock
339  * and job_unlock manually.  On the other hand, function called
340  * by the block jobs themselves and by the block layer will take the
341  * lock for you.
342  */
343 void job_lock(void);
344 
345 /**
346  * job_unlock:
347  *
348  * Release the mutex protecting the list of jobs and their status.
349  */
350 void job_unlock(void);
351 
352 /**
353  * Allocate and return a new job transaction. Jobs can be added to the
354  * transaction using job_txn_add_job().
355  *
356  * The transaction is automatically freed when the last job completes or is
357  * cancelled.
358  *
359  * All jobs in the transaction either complete successfully or fail/cancel as a
360  * group.  Jobs wait for each other before completing.  Cancelling one job
361  * cancels all jobs in the transaction.
362  */
363 JobTxn *job_txn_new(void);
364 
365 /**
366  * Release a reference that was previously acquired with job_txn_add_job or
367  * job_txn_new. If it's the last reference to the object, it will be freed.
368  *
369  * Called with job lock *not* held.
370  */
371 void job_txn_unref(JobTxn *txn);
372 
373 /*
374  * Same as job_txn_unref(), but called with job lock held.
375  * Might release the lock temporarily.
376  */
377 void job_txn_unref_locked(JobTxn *txn);
378 
379 /**
380  * Create a new long-running job and return it.
381  * Called with job_mutex *not* held.
382  *
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.
389  * @opaque: Opaque pointer value passed to @cb.
390  * @errp: Error object.
391  */
392 void *job_create(const char *job_id, const JobDriver *driver, JobTxn *txn,
393                  AioContext *ctx, int flags, BlockCompletionFunc *cb,
394                  void *opaque, Error **errp);
395 
396 /**
397  * Add a reference to Job refcnt, it will be decreased with job_unref, and then
398  * be freed if it comes to be the last reference.
399  *
400  * Called with job lock held.
401  */
402 void job_ref_locked(Job *job);
403 
404 /**
405  * Release a reference that was previously acquired with job_ref_locked() or
406  * job_create(). If it's the last reference to the object, it will be freed.
407  *
408  * Called with job lock held.
409  */
410 void job_unref_locked(Job *job);
411 
412 /**
413  * @job: The job that has made progress
414  * @done: How much progress the job made since the last call
415  *
416  * Updates the progress counter of the job.
417  *
418  * May be called with mutex held or not held.
419  */
420 void job_progress_update(Job *job, uint64_t done);
421 
422 /**
423  * @job: The job whose expected progress end value is set
424  * @remaining: Missing progress (on top of the current progress counter value)
425  *             until the new expected end value is reached
426  *
427  * Sets the expected end value of the progress counter of a job so that a
428  * completion percentage can be calculated when the progress is updated.
429  *
430  * May be called with mutex held or not held.
431  */
432 void job_progress_set_remaining(Job *job, uint64_t remaining);
433 
434 /**
435  * @job: The job whose expected progress end value is updated
436  * @delta: Value which is to be added to the current expected end
437  *         value
438  *
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
441  * conditionally perform a high-priority operation as part of its
442  * progress, it calls this function with the expected operation's
443  * length before, and job_progress_update() afterwards.
444  * (So the operation acts as a parenthesis in regards to the main job
445  * operation running in background.)
446  *
447  * May be called with mutex held or not held.
448  */
449 void job_progress_increase_remaining(Job *job, uint64_t delta);
450 
451 /**
452  * Conditionally enter the job coroutine if the job is ready to run, not
453  * already busy and fn() returns true. fn() is called while under the job_lock
454  * critical section.
455  *
456  * Called with job lock held, but might release it temporarily.
457  */
458 void job_enter_cond_locked(Job *job, bool(*fn)(Job *job));
459 
460 /**
461  * @job: A job that has not yet been started.
462  *
463  * Begins execution of a job.
464  * Takes ownership of one reference to the job object.
465  *
466  * Called with job_mutex *not* held.
467  */
468 void job_start(Job *job);
469 
470 /**
471  * @job: The job to enter.
472  *
473  * Continue the specified job by entering the coroutine.
474  * Called with job_mutex *not* held.
475  */
476 void job_enter(Job *job);
477 
478 /**
479  * @job: The job that is ready to pause.
480  *
481  * Pause now if job_pause() has been called. Jobs that perform lots of I/O
482  * must call this between requests so that the job can be paused.
483  *
484  * Called with job_mutex *not* held.
485  */
486 void coroutine_fn GRAPH_UNLOCKED job_pause_point(Job *job);
487 
488 /**
489  * @job: The job that calls the function.
490  *
491  * Yield the job coroutine.
492  * Called with job_mutex *not* held.
493  */
494 void coroutine_fn job_yield(Job *job);
495 
496 /**
497  * @job: The job that calls the function.
498  * @ns: How many nanoseconds to stop for.
499  *
500  * Put the job to sleep (assuming that it wasn't canceled) for @ns
501  * %QEMU_CLOCK_REALTIME nanoseconds.  Canceling the job will immediately
502  * interrupt the wait.
503  *
504  * Called with job_mutex *not* held.
505  */
506 void coroutine_fn job_sleep_ns(Job *job, int64_t ns);
507 
508 /** Returns the JobType of a given Job. */
509 JobType job_type(const Job *job);
510 
511 /** Returns the enum string for the JobType of a given Job. */
512 const char *job_type_str(const Job *job);
513 
514 /** Returns true if the job should not be visible to the management layer. */
515 bool job_is_internal(Job *job);
516 
517 /**
518  * Returns whether the job is being cancelled.
519  * Called with job_mutex *not* held.
520  */
521 bool job_is_cancelled(Job *job);
522 
523 /* Same as job_is_cancelled(), but called with job lock held. */
524 bool job_is_cancelled_locked(Job *job);
525 
526 /**
527  * Returns whether the job is scheduled for cancellation (at an
528  * indefinite point).
529  * Called with job_mutex *not* held.
530  */
531 bool job_cancel_requested(Job *job);
532 
533 /**
534  * Returns whether the job is in a completed state.
535  * Called with job lock held.
536  */
537 bool job_is_completed_locked(Job *job);
538 
539 /**
540  * Returns whether the job is ready to be completed.
541  * Called with job_mutex *not* held.
542  */
543 bool job_is_ready(Job *job);
544 
545 /* Same as job_is_ready(), but called with job lock held. */
546 bool job_is_ready_locked(Job *job);
547 
548 /**
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
551  * job_user_pause_locked() instead.
552  *
553  * Called with job lock *not* held.
554  */
555 void job_pause(Job *job);
556 
557 /* Same as job_pause(), but called with job lock held. */
558 void job_pause_locked(Job *job);
559 
560 /** Resumes a @job paused with job_pause. Called with job lock *not* held. */
561 void job_resume(Job *job);
562 
563 /*
564  * Same as job_resume(), but called with job lock held.
565  * Might release the lock temporarily.
566  */
567 void job_resume_locked(Job *job);
568 
569 /**
570  * Asynchronously pause the specified @job.
571  * Do not allow a resume until a matching call to job_user_resume.
572  * Called with job lock held.
573  */
574 void job_user_pause_locked(Job *job, Error **errp);
575 
576 /**
577  * Returns true if the job is user-paused.
578  * Called with job lock held.
579  */
580 bool job_user_paused_locked(Job *job);
581 
582 /**
583  * Resume the specified @job.
584  * Must be paired with a preceding job_user_pause_locked.
585  * Called with job lock held, but might release it temporarily.
586  */
587 void job_user_resume_locked(Job *job, Error **errp);
588 
589 /**
590  * Get the next element from the list of block jobs after @job, or the
591  * first one if @job is %NULL.
592  *
593  * Returns the requested job, or %NULL if there are no more jobs left.
594  * Called with job lock *not* held.
595  */
596 Job *job_next(Job *job);
597 
598 /* Same as job_next(), but called with job lock held. */
599 Job *job_next_locked(Job *job);
600 
601 /**
602  * Get the job identified by @id (which must not be %NULL).
603  *
604  * Returns the requested job, or %NULL if it doesn't exist.
605  * Called with job lock held.
606  */
607 Job *job_get_locked(const char *id);
608 
609 /**
610  * Check whether the verb @verb can be applied to @job in its current state.
611  * Returns 0 if the verb can be applied; otherwise errp is set and -EPERM
612  * returned.
613  *
614  * Called with job lock held.
615  */
616 int job_apply_verb_locked(Job *job, JobVerb verb, Error **errp);
617 
618 /**
619  * The @job could not be started, free it.
620  * Called with job_mutex *not* held.
621  */
622 void job_early_fail(Job *job);
623 
624 /**
625  * Moves the @job from RUNNING to READY.
626  * Called with job_mutex *not* held.
627  */
628 void job_transition_to_ready(Job *job);
629 
630 /**
631  * Asynchronously complete the specified @job.
632  * Called with job lock held, but might release it temporarily.
633  */
634 void job_complete_locked(Job *job, Error **errp);
635 
636 /**
637  * Asynchronously cancel the specified @job. If @force is true, the job should
638  * be cancelled immediately without waiting for a consistent state.
639  * Called with job lock held.
640  */
641 void job_cancel_locked(Job *job, bool force);
642 
643 /**
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.
647  */
648 void job_user_cancel_locked(Job *job, bool force, Error **errp);
649 
650 /**
651  * Synchronously cancel the @job.  The completion callback is called
652  * before the function returns.  If @force is false, the job may
653  * actually complete instead of canceling itself; the circumstances
654  * under which this happens depend on the kind of job that is active.
655  *
656  * Returns the return value from the job if the job actually completed
657  * during the call, or -ECANCELED if it was canceled.
658  *
659  * Called with job_lock *not* held.
660  */
661 int job_cancel_sync(Job *job, bool force);
662 
663 /* Same as job_cancel_sync, but called with job lock held. */
664 int job_cancel_sync_locked(Job *job, bool force);
665 
666 /**
667  * Synchronously force-cancels all jobs using job_cancel_sync_locked().
668  *
669  * Called with job_lock *not* held.
670  */
671 void job_cancel_sync_all(void);
672 
673 /**
674  * @job: The job to be completed.
675  * @errp: Error object which may be set by job_complete_locked(); this is not
676  *        necessarily set on every error, the job return value has to be
677  *        checked as well.
678  *
679  * Synchronously complete the job.  The completion callback is called before the
680  * function returns, unless it is NULL (which is permissible when using this
681  * function).
682  *
683  * Returns the return value from the job.
684  * Called with job_lock held.
685  */
686 int job_complete_sync_locked(Job *job, Error **errp);
687 
688 /**
689  * For a @job that has finished its work and is pending awaiting explicit
690  * acknowledgement to commit its work, this will commit that work.
691  *
692  * FIXME: Make the below statement universally true:
693  * For jobs that support the manual workflow mode, all graph changes that occur
694  * as a result will occur after this command and before a successful reply.
695  *
696  * Called with job lock held.
697  */
698 void job_finalize_locked(Job *job, Error **errp);
699 
700 /**
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.
703  *
704  * Called with job lock held.
705  */
706 void job_dismiss_locked(Job **job, Error **errp);
707 
708 /**
709  * Synchronously finishes the given @job. If @finish is given, it is called to
710  * trigger completion or cancellation of the job.
711  *
712  * Returns 0 if the job is successfully completed, -ECANCELED if the job was
713  * cancelled before completing, and -errno in other error cases.
714  *
715  * Called with job_lock held, but might release it temporarily.
716  */
717 int job_finish_sync_locked(Job *job, void (*finish)(Job *, Error **errp),
718                            Error **errp);
719 
720 /**
721  * Sets the @job->aio_context.
722  * Called with job_mutex *not* held.
723  *
724  * This function must run in the main thread to protect against
725  * concurrent read in job_finish_sync_locked(), takes the job_mutex
726  * lock to protect against the read in job_do_yield_locked(), and must
727  * be called when the job is quiescent.
728  */
729 void job_set_aio_context(Job *job, AioContext *ctx);
730 
731 #endif
732