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