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 block_job_enter().  There may still be I/O or event loop
  78      * activity pending.  Accessed under block_job_mutex (in blockjob.c).
  79      */
  80     bool busy;
  81
  82     /**
  83      * Set to true by the job while it is in a quiescent state, where
  84      * no I/O or event loop activity is pending.
  85      */
  86     bool paused;
  87
  88     /**
  89      * Set to true if the job is paused by user.  Can be unpaused with the
  90      * block-job-resume QMP command.
  91      */
  92     bool user_paused;
  93
  94     /**
  95      * Set to true if the job should cancel itself.  The flag must
  96      * always be tested just before toggling the busy flag from false
  97      * to true.  After a job has been cancelled, it should only yield
  98      * if #aio_poll will ("sooner or later") reenter the coroutine.
  99      */
 100     bool cancelled;
 101
 102     /**
 103      * Set to true if the job should abort immediately without waiting
 104      * for data to be in sync.
 105      */
 106     bool force_cancel;
 107
 108     /** Set to true when the job has deferred work to the main loop. */
 109     bool deferred_to_main_loop;
 110
 111     /** True if this job should automatically finalize itself */
 112     bool auto_finalize;
 113
 114     /** True if this job should automatically dismiss itself */
 115     bool auto_dismiss;
 116
 117     /** ret code passed to block_job_completed. */
 118     int ret;
 119
 120     /** The completion function that will be called when the job completes.  */
 121     BlockCompletionFunc *cb;
 122
 123     /** The opaque value that is passed to the completion function.  */
 124     void *opaque;
 125
 126     /** Notifiers called when a cancelled job is finalised */
 127     NotifierList on_finalize_cancelled;
 128
 129     /** Notifiers called when a successfully completed job is finalised */
 130     NotifierList on_finalize_completed;
 131
 132     /** Notifiers called when the job transitions to PENDING */
 133     NotifierList on_pending;
 134
 135     /** Element of the list of jobs */
 136     QLIST_ENTRY(Job) job_list;
 137
 138     /** Transaction this job is part of */
 139     JobTxn *txn;
 140
 141     /** Element of the list of jobs in a job transaction */
 142     QLIST_ENTRY(Job) txn_list;
 143 } Job;
 144
 145 /**
 146  * Callbacks and other information about a Job driver.
 147  */
 148 struct JobDriver {
 149     /** Derived Job struct size */
 150     size_t instance_size;
 151
 152     /** Enum describing the operation */
 153     JobType job_type;
 154
 155     /** Mandatory: Entrypoint for the Coroutine. */
 156     CoroutineEntry *start;
 157
 158     /**
 159      * If the callback is not NULL, it will be invoked when the job transitions
 160      * into the paused state.  Paused jobs must not perform any asynchronous
 161      * I/O or event loop activity.  This callback is used to quiesce jobs.
 162      */
 163     void coroutine_fn (*pause)(Job *job);
 164
 165     /**
 166      * If the callback is not NULL, it will be invoked when the job transitions
 167      * out of the paused state.  Any asynchronous I/O or event loop activity
 168      * should be restarted from this callback.
 169      */
 170     void coroutine_fn (*resume)(Job *job);
 171
 172     /**
 173      * Called when the job is resumed by the user (i.e. user_paused becomes
 174      * false). .user_resume is called before .resume.
 175      */
 176     void (*user_resume)(Job *job);
 177
 178     /**
 179      * Optional callback for job types whose completion must be triggered
 180      * manually.
 181      */
 182     void (*complete)(Job *job, Error **errp);
 183
 184     /*
 185      * If the callback is not NULL, it will be invoked when the job has to be
 186      * synchronously cancelled or completed; it should drain any activities
 187      * as required to ensure progress.
 188      */
 189     void (*drain)(Job *job);
 190
 191     /**
 192      * If the callback is not NULL, prepare will be invoked when all the jobs
 193      * belonging to the same transaction complete; or upon this job's completion
 194      * if it is not in a transaction.
 195      *
 196      * This callback will not be invoked if the job has already failed.
 197      * If it fails, abort and then clean will be called.
 198      */
 199     int (*prepare)(Job *job);
 200
 201     /**
 202      * If the callback is not NULL, it will be invoked when all the jobs
 203      * belonging to the same transaction complete; or upon this job's
 204      * completion if it is not in a transaction. Skipped if NULL.
 205      *
 206      * All jobs will complete with a call to either .commit() or .abort() but
 207      * never both.
 208      */
 209     void (*commit)(Job *job);
 210
 211     /**
 212      * If the callback is not NULL, it will be invoked when any job in the
 213      * same transaction fails; or upon this job's failure (due to error or
 214      * cancellation) if it is not in a transaction. Skipped if NULL.
 215      *
 216      * All jobs will complete with a call to either .commit() or .abort() but
 217      * never both.
 218      */
 219     void (*abort)(Job *job);
 220
 221     /**
 222      * If the callback is not NULL, it will be invoked after a call to either
 223      * .commit() or .abort(). Regardless of which callback is invoked after
 224      * completion, .clean() will always be called, even if the job does not
 225      * belong to a transaction group.
 226      */
 227     void (*clean)(Job *job);
 228
 229
 230     /** Called when the job is freed */
 231     void (*free)(Job *job);
 232 };
 233
 234 typedef enum JobCreateFlags {
 235     /* Default behavior */
 236     JOB_DEFAULT = 0x00,
 237     /* Job is not QMP-created and should not send QMP events */
 238     JOB_INTERNAL = 0x01,
 239     /* Job requires manual finalize step */
 240     JOB_MANUAL_FINALIZE = 0x02,
 241     /* Job requires manual dismiss step */
 242     JOB_MANUAL_DISMISS = 0x04,
 243 } JobCreateFlags;
 244
 245 /**
 246  * Allocate and return a new job transaction. Jobs can be added to the
 247  * transaction using job_txn_add_job().
 248  *
 249  * The transaction is automatically freed when the last job completes or is
 250  * cancelled.
 251  *
 252  * All jobs in the transaction either complete successfully or fail/cancel as a
 253  * group.  Jobs wait for each other before completing.  Cancelling one job
 254  * cancels all jobs in the transaction.
 255  */
 256 JobTxn *job_txn_new(void);
 257
 258 /**
 259  * Release a reference that was previously acquired with job_txn_add_job or
 260  * job_txn_new. If it's the last reference to the object, it will be freed.
 261  */
 262 void job_txn_unref(JobTxn *txn);
 263
 264 /**
 265  * @txn: The transaction (may be NULL)
 266  * @job: Job to add to the transaction
 267  *
 268  * Add @job to the transaction.  The @job must not already be in a transaction.
 269  * The caller must call either job_txn_unref() or block_job_completed() to
 270  * release the reference that is automatically grabbed here.
 271  *
 272  * If @txn is NULL, the function does nothing.
 273  */
 274 void job_txn_add_job(JobTxn *txn, Job *job);
 275
 276 /**
 277  * Create a new long-running job and return it.
 278  *
 279  * @job_id: The id of the newly-created job, or %NULL for internal jobs
 280  * @driver: The class object for the newly-created job.
 281  * @txn: The transaction this job belongs to, if any. %NULL otherwise.
 282  * @ctx: The AioContext to run the job coroutine in.
 283  * @flags: Creation flags for the job. See @JobCreateFlags.
 284  * @cb: Completion function for the job.
 285  * @opaque: Opaque pointer value passed to @cb.
 286  * @errp: Error object.
 287  */
 288 void *job_create(const char *job_id, const JobDriver *driver, JobTxn *txn,
 289                  AioContext *ctx, int flags, BlockCompletionFunc *cb,
 290                  void *opaque, Error **errp);
 291
 292 /**
 293  * Add a reference to Job refcnt, it will be decreased with job_unref, and then
 294  * be freed if it comes to be the last reference.
 295  */
 296 void job_ref(Job *job);
 297
 298 /**
 299  * Release a reference that was previously acquired with job_ref() or
 300  * job_create(). If it's the last reference to the object, it will be freed.
 301  */
 302 void job_unref(Job *job);
 303
 304 /** To be called when a cancelled job is finalised. */
 305 void job_event_cancelled(Job *job);
 306
 307 /** To be called when a successfully completed job is finalised. */
 308 void job_event_completed(Job *job);
 309
 310 /**
 311  * Conditionally enter the job coroutine if the job is ready to run, not
 312  * already busy and fn() returns true. fn() is called while under the job_lock
 313  * critical section.
 314  */
 315 void job_enter_cond(Job *job, bool(*fn)(Job *job));
 316
 317 /**
 318  * @job: A job that has not yet been started.
 319  *
 320  * Begins execution of a job.
 321  * Takes ownership of one reference to the job object.
 322  */
 323 void job_start(Job *job);
 324
 325 /**
 326  * @job: The job to enter.
 327  *
 328  * Continue the specified job by entering the coroutine.
 329  */
 330 void job_enter(Job *job);
 331
 332 /**
 333  * @job: The job that is ready to pause.
 334  *
 335  * Pause now if job_pause() has been called. Jobs that perform lots of I/O
 336  * must call this between requests so that the job can be paused.
 337  */
 338 void coroutine_fn job_pause_point(Job *job);
 339
 340 /**
 341  * @job: The job that calls the function.
 342  * @ns: How many nanoseconds to stop for.
 343  *
 344  * Put the job to sleep (assuming that it wasn't canceled) for @ns
 345  * %QEMU_CLOCK_REALTIME nanoseconds.  Canceling the job will immediately
 346  * interrupt the wait.
 347  */
 348 void coroutine_fn job_sleep_ns(Job *job, int64_t ns);
 349
 350
 351 /** Returns the JobType of a given Job. */
 352 JobType job_type(const Job *job);
 353
 354 /** Returns the enum string for the JobType of a given Job. */
 355 const char *job_type_str(const Job *job);
 356
 357 /** Returns whether the job is scheduled for cancellation. */
 358 bool job_is_cancelled(Job *job);
 359
 360 /** Returns whether the job is in a completed state. */
 361 bool job_is_completed(Job *job);
 362
 363 /**
 364  * Request @job to pause at the next pause point. Must be paired with
 365  * job_resume(). If the job is supposed to be resumed by user action, call
 366  * job_user_pause() instead.
 367  */
 368 void job_pause(Job *job);
 369
 370 /** Resumes a @job paused with job_pause. */
 371 void job_resume(Job *job);
 372
 373 /**
 374  * Asynchronously pause the specified @job.
 375  * Do not allow a resume until a matching call to job_user_resume.
 376  */
 377 void job_user_pause(Job *job, Error **errp);
 378
 379 /** Returns true if the job is user-paused. */
 380 bool job_user_paused(Job *job);
 381
 382 /**
 383  * Resume the specified @job.
 384  * Must be paired with a preceding job_user_pause.
 385  */
 386 void job_user_resume(Job *job, Error **errp);
 387
 388 /*
 389  * Drain any activities as required to ensure progress. This can be called in a
 390  * loop to synchronously complete a job.
 391  */
 392 void job_drain(Job *job);
 393
 394 /**
 395  * Get the next element from the list of block jobs after @job, or the
 396  * first one if @job is %NULL.
 397  *
 398  * Returns the requested job, or %NULL if there are no more jobs left.
 399  */
 400 Job *job_next(Job *job);
 401
 402 /**
 403  * Get the job identified by @id (which must not be %NULL).
 404  *
 405  * Returns the requested job, or %NULL if it doesn't exist.
 406  */
 407 Job *job_get(const char *id);
 408
 409 /**
 410  * Check whether the verb @verb can be applied to @job in its current state.
 411  * Returns 0 if the verb can be applied; otherwise errp is set and -EPERM
 412  * returned.
 413  */
 414 int job_apply_verb(Job *job, JobVerb verb, Error **errp);
 415
 416 /** The @job could not be started, free it. */
 417 void job_early_fail(Job *job);
 418
 419 /** Asynchronously complete the specified @job. */
 420 void job_complete(Job *job, Error **errp);;
 421
 422 /**
 423  * For a @job that has finished its work and is pending awaiting explicit
 424  * acknowledgement to commit its work, this will commit that work.
 425  *
 426  * FIXME: Make the below statement universally true:
 427  * For jobs that support the manual workflow mode, all graph changes that occur
 428  * as a result will occur after this command and before a successful reply.
 429  */
 430 void job_finalize(Job *job, Error **errp);
 431
 432 typedef void JobDeferToMainLoopFn(Job *job, void *opaque);
 433
 434 /**
 435  * @job: The job
 436  * @fn: The function to run in the main loop
 437  * @opaque: The opaque value that is passed to @fn
 438  *
 439  * This function must be called by the main job coroutine just before it
 440  * returns.  @fn is executed in the main loop with the job AioContext acquired.
 441  *
 442  * Block jobs must call bdrv_unref(), bdrv_close(), and anything that uses
 443  * bdrv_drain_all() in the main loop.
 444  *
 445  * The @job AioContext is held while @fn executes.
 446  */
 447 void job_defer_to_main_loop(Job *job, JobDeferToMainLoopFn *fn, void *opaque);
 448
 449 /**
 450  * Synchronously finishes the given @job. If @finish is given, it is called to
 451  * trigger completion or cancellation of the job.
 452  *
 453  * Returns 0 if the job is successfully completed, -ECANCELED if the job was
 454  * cancelled before completing, and -errno in other error cases.
 455  */
 456 int job_finish_sync(Job *job, void (*finish)(Job *, Error **errp), Error **errp);
 457
 458 /* TODO To be removed from the public interface */
 459 void job_state_transition(Job *job, JobStatus s1);
 460 void coroutine_fn job_do_yield(Job *job, uint64_t ns);
 461 bool job_should_pause(Job *job);
 462 bool job_started(Job *job);
 463 void job_do_dismiss(Job *job);
 464 void job_update_rc(Job *job);
 465 void job_cancel_async(Job *job, bool force);
 466 void job_completed_txn_abort(Job *job);
 467 void job_completed_txn_success(Job *job);
 468
 469 #endif