include/qemu/job.h

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