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 extern QemuMutex job_mutex; 307 308 #define JOB_LOCK_GUARD() /* QEMU_LOCK_GUARD(&job_mutex) */ 309 310 #define WITH_JOB_LOCK_GUARD() /* WITH_QEMU_LOCK_GUARD(&job_mutex) */ 311 312 /** 313 * job_lock: 314 * 315 * Take the mutex protecting the list of jobs and their status. 316 * Most functions called by the monitor need to call job_lock 317 * and job_unlock manually. On the other hand, function called 318 * by the block jobs themselves and by the block layer will take the 319 * lock for you. 320 */ 321 void job_lock(void); 322 323 /** 324 * job_unlock: 325 * 326 * Release the mutex protecting the list of jobs and their status. 327 */ 328 void job_unlock(void); 329 330 /** 331 * Allocate and return a new job transaction. Jobs can be added to the 332 * transaction using job_txn_add_job(). 333 * 334 * The transaction is automatically freed when the last job completes or is 335 * cancelled. 336 * 337 * All jobs in the transaction either complete successfully or fail/cancel as a 338 * group. Jobs wait for each other before completing. Cancelling one job 339 * cancels all jobs in the transaction. 340 */ 341 JobTxn *job_txn_new(void); 342 343 /** 344 * Release a reference that was previously acquired with job_txn_add_job or 345 * job_txn_new. If it's the last reference to the object, it will be freed. 346 */ 347 void job_txn_unref(JobTxn *txn); 348 349 /** 350 * @txn: The transaction (may be NULL) 351 * @job: Job to add to the transaction 352 * 353 * Add @job to the transaction. The @job must not already be in a transaction. 354 * The caller must call either job_txn_unref() or job_completed() to release 355 * the reference that is automatically grabbed here. 356 * 357 * If @txn is NULL, the function does nothing. 358 */ 359 void job_txn_add_job(JobTxn *txn, Job *job); 360 361 /** 362 * Create a new long-running job and return it. 363 * 364 * @job_id: The id of the newly-created job, or %NULL for internal jobs 365 * @driver: The class object for the newly-created job. 366 * @txn: The transaction this job belongs to, if any. %NULL otherwise. 367 * @ctx: The AioContext to run the job coroutine in. 368 * @flags: Creation flags for the job. See @JobCreateFlags. 369 * @cb: Completion function for the job. 370 * @opaque: Opaque pointer value passed to @cb. 371 * @errp: Error object. 372 */ 373 void *job_create(const char *job_id, const JobDriver *driver, JobTxn *txn, 374 AioContext *ctx, int flags, BlockCompletionFunc *cb, 375 void *opaque, Error **errp); 376 377 /** 378 * Add a reference to Job refcnt, it will be decreased with job_unref, and then 379 * be freed if it comes to be the last reference. 380 */ 381 void job_ref(Job *job); 382 383 /** 384 * Release a reference that was previously acquired with job_ref() or 385 * job_create(). If it's the last reference to the object, it will be freed. 386 */ 387 void job_unref(Job *job); 388 389 /** 390 * @job: The job that has made progress 391 * @done: How much progress the job made since the last call 392 * 393 * Updates the progress counter of the job. 394 */ 395 void job_progress_update(Job *job, uint64_t done); 396 397 /** 398 * @job: The job whose expected progress end value is set 399 * @remaining: Missing progress (on top of the current progress counter value) 400 * until the new expected end value is reached 401 * 402 * Sets the expected end value of the progress counter of a job so that a 403 * completion percentage can be calculated when the progress is updated. 404 */ 405 void job_progress_set_remaining(Job *job, uint64_t remaining); 406 407 /** 408 * @job: The job whose expected progress end value is updated 409 * @delta: Value which is to be added to the current expected end 410 * value 411 * 412 * Increases the expected end value of the progress counter of a job. 413 * This is useful for parenthesis operations: If a job has to 414 * conditionally perform a high-priority operation as part of its 415 * progress, it calls this function with the expected operation's 416 * length before, and job_progress_update() afterwards. 417 * (So the operation acts as a parenthesis in regards to the main job 418 * operation running in background.) 419 */ 420 void job_progress_increase_remaining(Job *job, uint64_t delta); 421 422 /** To be called when a cancelled job is finalised. */ 423 void job_event_cancelled(Job *job); 424 425 /** To be called when a successfully completed job is finalised. */ 426 void job_event_completed(Job *job); 427 428 /** 429 * Conditionally enter the job coroutine if the job is ready to run, not 430 * already busy and fn() returns true. fn() is called while under the job_lock 431 * critical section. 432 */ 433 void job_enter_cond(Job *job, bool(*fn)(Job *job)); 434 435 /** 436 * @job: A job that has not yet been started. 437 * 438 * Begins execution of a job. 439 * Takes ownership of one reference to the job object. 440 */ 441 void job_start(Job *job); 442 443 /** 444 * @job: The job to enter. 445 * 446 * Continue the specified job by entering the coroutine. 447 */ 448 void job_enter(Job *job); 449 450 /** 451 * @job: The job that is ready to pause. 452 * 453 * Pause now if job_pause() has been called. Jobs that perform lots of I/O 454 * must call this between requests so that the job can be paused. 455 */ 456 void coroutine_fn job_pause_point(Job *job); 457 458 /** 459 * @job: The job that calls the function. 460 * 461 * Yield the job coroutine. 462 */ 463 void coroutine_fn job_yield(Job *job); 464 465 /** 466 * @job: The job that calls the function. 467 * @ns: How many nanoseconds to stop for. 468 * 469 * Put the job to sleep (assuming that it wasn't canceled) for @ns 470 * %QEMU_CLOCK_REALTIME nanoseconds. Canceling the job will immediately 471 * interrupt the wait. 472 */ 473 void coroutine_fn job_sleep_ns(Job *job, int64_t ns); 474 475 476 /** Returns the JobType of a given Job. */ 477 JobType job_type(const Job *job); 478 479 /** Returns the enum string for the JobType of a given Job. */ 480 const char *job_type_str(const Job *job); 481 482 /** Returns true if the job should not be visible to the management layer. */ 483 bool job_is_internal(Job *job); 484 485 /** Returns whether the job is being cancelled. */ 486 bool job_is_cancelled(Job *job); 487 488 /** 489 * Returns whether the job is scheduled for cancellation (at an 490 * indefinite point). 491 */ 492 bool job_cancel_requested(Job *job); 493 494 /** Returns whether the job is in a completed state. */ 495 bool job_is_completed(Job *job); 496 497 /** Returns whether the job is ready to be completed. */ 498 bool job_is_ready(Job *job); 499 500 /** 501 * Request @job to pause at the next pause point. Must be paired with 502 * job_resume(). If the job is supposed to be resumed by user action, call 503 * job_user_pause() instead. 504 */ 505 void job_pause(Job *job); 506 507 /** Resumes a @job paused with job_pause. */ 508 void job_resume(Job *job); 509 510 /** 511 * Asynchronously pause the specified @job. 512 * Do not allow a resume until a matching call to job_user_resume. 513 */ 514 void job_user_pause(Job *job, Error **errp); 515 516 /** Returns true if the job is user-paused. */ 517 bool job_user_paused(Job *job); 518 519 /** 520 * Resume the specified @job. 521 * Must be paired with a preceding job_user_pause. 522 */ 523 void job_user_resume(Job *job, Error **errp); 524 525 /** 526 * Get the next element from the list of block jobs after @job, or the 527 * first one if @job is %NULL. 528 * 529 * Returns the requested job, or %NULL if there are no more jobs left. 530 */ 531 Job *job_next(Job *job); 532 533 /** 534 * Get the job identified by @id (which must not be %NULL). 535 * 536 * Returns the requested job, or %NULL if it doesn't exist. 537 */ 538 Job *job_get(const char *id); 539 540 /** 541 * Check whether the verb @verb can be applied to @job in its current state. 542 * Returns 0 if the verb can be applied; otherwise errp is set and -EPERM 543 * returned. 544 */ 545 int job_apply_verb(Job *job, JobVerb verb, Error **errp); 546 547 /** The @job could not be started, free it. */ 548 void job_early_fail(Job *job); 549 550 /** Moves the @job from RUNNING to READY */ 551 void job_transition_to_ready(Job *job); 552 553 /** Asynchronously complete the specified @job. */ 554 void job_complete(Job *job, Error **errp); 555 556 /** 557 * Asynchronously cancel the specified @job. If @force is true, the job should 558 * be cancelled immediately without waiting for a consistent state. 559 */ 560 void job_cancel(Job *job, bool force); 561 562 /** 563 * Cancels the specified job like job_cancel(), but may refuse to do so if the 564 * operation isn't meaningful in the current state of the job. 565 */ 566 void job_user_cancel(Job *job, bool force, Error **errp); 567 568 /** 569 * Synchronously cancel the @job. The completion callback is called 570 * before the function returns. If @force is false, the job may 571 * actually complete instead of canceling itself; the circumstances 572 * under which this happens depend on the kind of job that is active. 573 * 574 * Returns the return value from the job if the job actually completed 575 * during the call, or -ECANCELED if it was canceled. 576 * 577 * Callers must hold the AioContext lock of job->aio_context. 578 */ 579 int job_cancel_sync(Job *job, bool force); 580 581 /** Synchronously force-cancels all jobs using job_cancel_sync(). */ 582 void job_cancel_sync_all(void); 583 584 /** 585 * @job: The job to be completed. 586 * @errp: Error object which may be set by job_complete(); this is not 587 * necessarily set on every error, the job return value has to be 588 * checked as well. 589 * 590 * Synchronously complete the job. The completion callback is called before the 591 * function returns, unless it is NULL (which is permissible when using this 592 * function). 593 * 594 * Returns the return value from the job. 595 * 596 * Callers must hold the AioContext lock of job->aio_context. 597 */ 598 int job_complete_sync(Job *job, Error **errp); 599 600 /** 601 * For a @job that has finished its work and is pending awaiting explicit 602 * acknowledgement to commit its work, this will commit that work. 603 * 604 * FIXME: Make the below statement universally true: 605 * For jobs that support the manual workflow mode, all graph changes that occur 606 * as a result will occur after this command and before a successful reply. 607 */ 608 void job_finalize(Job *job, Error **errp); 609 610 /** 611 * Remove the concluded @job from the query list and resets the passed pointer 612 * to %NULL. Returns an error if the job is not actually concluded. 613 */ 614 void job_dismiss(Job **job, Error **errp); 615 616 /** 617 * Synchronously finishes the given @job. If @finish is given, it is called to 618 * trigger completion or cancellation of the job. 619 * 620 * Returns 0 if the job is successfully completed, -ECANCELED if the job was 621 * cancelled before completing, and -errno in other error cases. 622 * 623 * Callers must hold the AioContext lock of job->aio_context. 624 */ 625 int job_finish_sync(Job *job, void (*finish)(Job *, Error **errp), Error **errp); 626 627 #endif 628