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