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
  36 /**
  37  * Long-running operation.
  38  */
  39 typedef struct Job {
  40     /** The ID of the job. May be NULL for internal jobs. */
  41     char *id;
  42
  43     /** The type of this job. */
  44     const JobDriver *driver;
  45
  46     /** Reference count of the block job */
  47     int refcnt;
  48
  49     /** Current state; See @JobStatus for details. */
  50     JobStatus status;
  51
  52     /** AioContext to run the job coroutine in */
  53     AioContext *aio_context;
  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      */
  59     Coroutine *co;
  60
  61     /**
  62      * Timer that is used by @job_sleep_ns. Accessed under job_mutex (in
  63      * job.c).
  64      */
  65     QEMUTimer sleep_timer;
  66
  67     /**
  68      * Counter for pause request. If non-zero, the block job is either paused,
  69      * or if busy == true will pause itself as soon as possible.
  70      */
  71     int pause_count;
  72
  73     /**
  74      * Set to false by the job while the coroutine has yielded and may be
  75      * re-entered by block_job_enter().  There may still be I/O or event loop
  76      * activity pending.  Accessed under block_job_mutex (in blockjob.c).
  77      */
  78     bool busy;
  79
  80     /**
  81      * Set to true by the job while it is in a quiescent state, where
  82      * no I/O or event loop activity is pending.
  83      */
  84     bool paused;
  85
  86     /**
  87      * Set to true if the job is paused by user.  Can be unpaused with the
  88      * block-job-resume QMP command.
  89      */
  90     bool user_paused;
  91
  92     /**
  93      * Set to true if the job should cancel itself.  The flag must
  94      * always be tested just before toggling the busy flag from false
  95      * to true.  After a job has been cancelled, it should only yield
  96      * if #aio_poll will ("sooner or later") reenter the coroutine.
  97      */
  98     bool cancelled;
  99
 100     /**
 101      * Set to true if the job should abort immediately without waiting
 102      * for data to be in sync.
 103      */
 104     bool force_cancel;
 105
 106     /** Set to true when the job has deferred work to the main loop. */
 107     bool deferred_to_main_loop;
 108
 109     /** True if this job should automatically finalize itself */
 110     bool auto_finalize;
 111
 112     /** True if this job should automatically dismiss itself */
 113     bool auto_dismiss;
 114
 115     /** ret code passed to block_job_completed. */
 116     int ret;
 117
 118     /** The completion function that will be called when the job completes.  */
 119     BlockCompletionFunc *cb;
 120
 121     /** The opaque value that is passed to the completion function.  */
 122     void *opaque;
 123
 124     /** Notifiers called when a cancelled job is finalised */
 125     NotifierList on_finalize_cancelled;
 126
 127     /** Notifiers called when a successfully completed job is finalised */
 128     NotifierList on_finalize_completed;
 129
 130     /** Notifiers called when the job transitions to PENDING */
 131     NotifierList on_pending;
 132
 133     /** Element of the list of jobs */
 134     QLIST_ENTRY(Job) job_list;
 135 } Job;
 136
 137 /**
 138  * Callbacks and other information about a Job driver.
 139  */
 140 struct JobDriver {
 141     /** Derived Job struct size */
 142     size_t instance_size;
 143
 144     /** Enum describing the operation */
 145     JobType job_type;
 146
 147     /** Mandatory: Entrypoint for the Coroutine. */
 148     CoroutineEntry *start;
 149
 150     /**
 151      * If the callback is not NULL, it will be invoked when the job transitions
 152      * into the paused state.  Paused jobs must not perform any asynchronous
 153      * I/O or event loop activity.  This callback is used to quiesce jobs.
 154      */
 155     void coroutine_fn (*pause)(Job *job);
 156
 157     /**
 158      * If the callback is not NULL, it will be invoked when the job transitions
 159      * out of the paused state.  Any asynchronous I/O or event loop activity
 160      * should be restarted from this callback.
 161      */
 162     void coroutine_fn (*resume)(Job *job);
 163
 164     /**
 165      * Called when the job is resumed by the user (i.e. user_paused becomes
 166      * false). .user_resume is called before .resume.
 167      */
 168     void (*user_resume)(Job *job);
 169
 170     /**
 171      * If the callback is not NULL, it will be invoked when all the jobs
 172      * belonging to the same transaction complete; or upon this job's
 173      * completion if it is not in a transaction. Skipped if NULL.
 174      *
 175      * All jobs will complete with a call to either .commit() or .abort() but
 176      * never both.
 177      */
 178     void (*commit)(Job *job);
 179
 180     /**
 181      * If the callback is not NULL, it will be invoked when any job in the
 182      * same transaction fails; or upon this job's failure (due to error or
 183      * cancellation) if it is not in a transaction. Skipped if NULL.
 184      *
 185      * All jobs will complete with a call to either .commit() or .abort() but
 186      * never both.
 187      */
 188     void (*abort)(Job *job);
 189
 190     /**
 191      * If the callback is not NULL, it will be invoked after a call to either
 192      * .commit() or .abort(). Regardless of which callback is invoked after
 193      * completion, .clean() will always be called, even if the job does not
 194      * belong to a transaction group.
 195      */
 196     void (*clean)(Job *job);
 197
 198
 199     /** Called when the job is freed */
 200     void (*free)(Job *job);
 201 };
 202
 203 typedef enum JobCreateFlags {
 204     /* Default behavior */
 205     JOB_DEFAULT = 0x00,
 206     /* Job is not QMP-created and should not send QMP events */
 207     JOB_INTERNAL = 0x01,
 208     /* Job requires manual finalize step */
 209     JOB_MANUAL_FINALIZE = 0x02,
 210     /* Job requires manual dismiss step */
 211     JOB_MANUAL_DISMISS = 0x04,
 212 } JobCreateFlags;
 213
 214
 215 /**
 216  * Create a new long-running job and return it.
 217  *
 218  * @job_id: The id of the newly-created job, or %NULL for internal jobs
 219  * @driver: The class object for the newly-created job.
 220  * @ctx: The AioContext to run the job coroutine in.
 221  * @flags: Creation flags for the job. See @JobCreateFlags.
 222  * @cb: Completion function for the job.
 223  * @opaque: Opaque pointer value passed to @cb.
 224  * @errp: Error object.
 225  */
 226 void *job_create(const char *job_id, const JobDriver *driver, AioContext *ctx,
 227                  int flags, BlockCompletionFunc *cb, void *opaque, Error **errp);
 228
 229 /**
 230  * Add a reference to Job refcnt, it will be decreased with job_unref, and then
 231  * be freed if it comes to be the last reference.
 232  */
 233 void job_ref(Job *job);
 234
 235 /**
 236  * Release a reference that was previously acquired with job_ref() or
 237  * job_create(). If it's the last reference to the object, it will be freed.
 238  */
 239 void job_unref(Job *job);
 240
 241 /** To be called when a cancelled job is finalised. */
 242 void job_event_cancelled(Job *job);
 243
 244 /** To be called when a successfully completed job is finalised. */
 245 void job_event_completed(Job *job);
 246
 247 /** To be called when the job transitions to PENDING */
 248 void job_event_pending(Job *job);
 249
 250 /**
 251  * Conditionally enter the job coroutine if the job is ready to run, not
 252  * already busy and fn() returns true. fn() is called while under the job_lock
 253  * critical section.
 254  */
 255 void job_enter_cond(Job *job, bool(*fn)(Job *job));
 256
 257 /**
 258  * @job: A job that has not yet been started.
 259  *
 260  * Begins execution of a job.
 261  * Takes ownership of one reference to the job object.
 262  */
 263 void job_start(Job *job);
 264
 265 /**
 266  * @job: The job to enter.
 267  *
 268  * Continue the specified job by entering the coroutine.
 269  */
 270 void job_enter(Job *job);
 271
 272 /**
 273  * @job: The job that is ready to pause.
 274  *
 275  * Pause now if job_pause() has been called. Jobs that perform lots of I/O
 276  * must call this between requests so that the job can be paused.
 277  */
 278 void coroutine_fn job_pause_point(Job *job);
 279
 280 /**
 281  * @job: The job that calls the function.
 282  * @ns: How many nanoseconds to stop for.
 283  *
 284  * Put the job to sleep (assuming that it wasn't canceled) for @ns
 285  * %QEMU_CLOCK_REALTIME nanoseconds.  Canceling the job will immediately
 286  * interrupt the wait.
 287  */
 288 void coroutine_fn job_sleep_ns(Job *job, int64_t ns);
 289
 290
 291 /** Returns the JobType of a given Job. */
 292 JobType job_type(const Job *job);
 293
 294 /** Returns the enum string for the JobType of a given Job. */
 295 const char *job_type_str(const Job *job);
 296
 297 /** Returns whether the job is scheduled for cancellation. */
 298 bool job_is_cancelled(Job *job);
 299
 300 /** Returns whether the job is in a completed state. */
 301 bool job_is_completed(Job *job);
 302
 303 /**
 304  * Request @job to pause at the next pause point. Must be paired with
 305  * job_resume(). If the job is supposed to be resumed by user action, call
 306  * job_user_pause() instead.
 307  */
 308 void job_pause(Job *job);
 309
 310 /** Resumes a @job paused with job_pause. */
 311 void job_resume(Job *job);
 312
 313 /**
 314  * Asynchronously pause the specified @job.
 315  * Do not allow a resume until a matching call to job_user_resume.
 316  */
 317 void job_user_pause(Job *job, Error **errp);
 318
 319 /** Returns true if the job is user-paused. */
 320 bool job_user_paused(Job *job);
 321
 322 /**
 323  * Resume the specified @job.
 324  * Must be paired with a preceding job_user_pause.
 325  */
 326 void job_user_resume(Job *job, Error **errp);
 327
 328 /**
 329  * Get the next element from the list of block jobs after @job, or the
 330  * first one if @job is %NULL.
 331  *
 332  * Returns the requested job, or %NULL if there are no more jobs left.
 333  */
 334 Job *job_next(Job *job);
 335
 336 /**
 337  * Get the job identified by @id (which must not be %NULL).
 338  *
 339  * Returns the requested job, or %NULL if it doesn't exist.
 340  */
 341 Job *job_get(const char *id);
 342
 343 /**
 344  * Check whether the verb @verb can be applied to @job in its current state.
 345  * Returns 0 if the verb can be applied; otherwise errp is set and -EPERM
 346  * returned.
 347  */
 348 int job_apply_verb(Job *job, JobVerb verb, Error **errp);
 349
 350 /** The @job could not be started, free it. */
 351 void job_early_fail(Job *job);
 352
 353
 354 typedef void JobDeferToMainLoopFn(Job *job, void *opaque);
 355
 356 /**
 357  * @job: The job
 358  * @fn: The function to run in the main loop
 359  * @opaque: The opaque value that is passed to @fn
 360  *
 361  * This function must be called by the main job coroutine just before it
 362  * returns.  @fn is executed in the main loop with the job AioContext acquired.
 363  *
 364  * Block jobs must call bdrv_unref(), bdrv_close(), and anything that uses
 365  * bdrv_drain_all() in the main loop.
 366  *
 367  * The @job AioContext is held while @fn executes.
 368  */
 369 void job_defer_to_main_loop(Job *job, JobDeferToMainLoopFn *fn, void *opaque);
 370
 371 /* TODO To be removed from the public interface */
 372 void job_state_transition(Job *job, JobStatus s1);
 373 void coroutine_fn job_do_yield(Job *job, uint64_t ns);
 374 bool job_should_pause(Job *job);
 375 bool job_started(Job *job);
 376 void job_do_dismiss(Job *job);
 377 int job_finalize_single(Job *job);
 378 void job_update_rc(Job *job);
 379
 380 typedef struct BlockJob BlockJob;
 381 void block_job_txn_del_job(BlockJob *job);
 382
 383 #endif