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 34typedef struct JobDriver JobDriver; 35typedef struct JobTxn JobTxn; 36 37 38/** 39 * Long-running operation. 40 */ 41typedef 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 */ 178struct 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 273typedef 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 */ 295JobTxn *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 */ 301void 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 */ 313void 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 */ 327void *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 */ 335void 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 */ 341void 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 */ 349void 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 */ 359void 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 */ 374void job_progress_increase_remaining(Job *job, uint64_t delta); 375 376/** To be called when a cancelled job is finalised. */ 377void job_event_cancelled(Job *job); 378 379/** To be called when a successfully completed job is finalised. */ 380void 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 */ 387void 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 */ 395void job_start(Job *job); 396 397/** 398 * @job: The job to enter. 399 * 400 * Continue the specified job by entering the coroutine. 401 */ 402void 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 */ 410void coroutine_fn job_pause_point(Job *job); 411 412/** 413 * @job: The job that calls the function. 414 * 415 * Yield the job coroutine. 416 */ 417void 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 */ 427void coroutine_fn job_sleep_ns(Job *job, int64_t ns); 428 429 430/** Returns the JobType of a given Job. */ 431JobType job_type(const Job *job); 432 433/** Returns the enum string for the JobType of a given Job. */ 434const char *job_type_str(const Job *job); 435 436/** Returns true if the job should not be visible to the management layer. */ 437bool job_is_internal(Job *job); 438 439/** Returns whether the job is scheduled for cancellation. */ 440bool job_is_cancelled(Job *job); 441 442/** Returns whether the job is in a completed state. */ 443bool job_is_completed(Job *job); 444 445/** Returns whether the job is ready to be completed. */ 446bool 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 */ 453void job_pause(Job *job); 454 455/** Resumes a @job paused with job_pause. */ 456void 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 */ 462void job_user_pause(Job *job, Error **errp); 463 464/** Returns true if the job is user-paused. */ 465bool job_user_paused(Job *job); 466 467/** 468 * Resume the specified @job. 469 * Must be paired with a preceding job_user_pause. 470 */ 471void 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 */ 477void 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 */ 485Job *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 */ 492Job *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 */ 499int job_apply_verb(Job *job, JobVerb verb, Error **errp); 500 501/** The @job could not be started, free it. */ 502void job_early_fail(Job *job); 503 504/** Moves the @job from RUNNING to READY */ 505void job_transition_to_ready(Job *job); 506 507/** Asynchronously complete the specified @job. */ 508void 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 */ 514void 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 */ 520void 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 */ 533int job_cancel_sync(Job *job); 534 535/** Synchronously cancels all jobs using job_cancel_sync(). */ 536void 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 */ 552int 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 */ 562void 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 */ 568void 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 */ 579int job_finish_sync(Job *job, void (*finish)(Job *, Error **errp), Error **errp); 580 581#endif 582