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 44 /* Fields set at initialization (job_create), and never modified */ 45 46 /** The ID of the job. May be NULL for internal jobs. */ 47 char *id; 48 49 /** 50 * The type of this job. 51 * All callbacks are called with job_mutex *not* held. 52 */ 53 const JobDriver *driver; 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 * Initialized in job_start() 59 */ 60 Coroutine *co; 61 62 /** True if this job should automatically finalize itself */ 63 bool auto_finalize; 64 65 /** True if this job should automatically dismiss itself */ 66 bool auto_dismiss; 67 68 /** The completion function that will be called when the job completes. */ 69 BlockCompletionFunc *cb; 70 71 /** The opaque value that is passed to the completion function. */ 72 void *opaque; 73 74 /* ProgressMeter API is thread-safe */ 75 ProgressMeter progress; 76 77 78 /** Protected by AioContext lock */ 79 80 /** AioContext to run the job coroutine in */ 81 AioContext *aio_context; 82 83 /** Reference count of the block job */ 84 int refcnt; 85 86 /** Current state; See @JobStatus for details. */ 87 JobStatus status; 88 89 /** 90 * Timer that is used by @job_sleep_ns. Accessed under job_mutex (in 91 * job.c). 92 */ 93 QEMUTimer sleep_timer; 94 95 /** 96 * Counter for pause request. If non-zero, the block job is either paused, 97 * or if busy == true will pause itself as soon as possible. 98 */ 99 int pause_count; 100 101 /** 102 * Set to false by the job while the coroutine has yielded and may be 103 * re-entered by job_enter(). There may still be I/O or event loop activity 104 * pending. Accessed under block_job_mutex (in blockjob.c). 105 * 106 * When the job is deferred to the main loop, busy is true as long as the 107 * bottom half is still pending. 108 */ 109 bool busy; 110 111 /** 112 * Set to true by the job while it is in a quiescent state, where 113 * no I/O or event loop activity is pending. 114 */ 115 bool paused; 116 117 /** 118 * Set to true if the job is paused by user. Can be unpaused with the 119 * block-job-resume QMP command. 120 */ 121 bool user_paused; 122 123 /** 124 * Set to true if the job should cancel itself. The flag must 125 * always be tested just before toggling the busy flag from false 126 * to true. After a job has been cancelled, it should only yield 127 * if #aio_poll will ("sooner or later") reenter the coroutine. 128 */ 129 bool cancelled; 130 131 /** 132 * Set to true if the job should abort immediately without waiting 133 * for data to be in sync. 134 */ 135 bool force_cancel; 136 137 /** Set to true when the job has deferred work to the main loop. */ 138 bool deferred_to_main_loop; 139 140 /** 141 * Return code from @run and/or @prepare callback(s). 142 * Not final until the job has reached the CONCLUDED status. 143 * 0 on success, -errno on failure. 144 */ 145 int ret; 146 147 /** 148 * Error object for a failed job. 149 * If job->ret is nonzero and an error object was not set, it will be set 150 * to strerror(-job->ret) during job_completed. 151 */ 152 Error *err; 153 154 /** Notifiers called when a cancelled job is finalised */ 155 NotifierList on_finalize_cancelled; 156 157 /** Notifiers called when a successfully completed job is finalised */ 158 NotifierList on_finalize_completed; 159 160 /** Notifiers called when the job transitions to PENDING */ 161 NotifierList on_pending; 162 163 /** Notifiers called when the job transitions to READY */ 164 NotifierList on_ready; 165 166 /** Notifiers called when the job coroutine yields or terminates */ 167 NotifierList on_idle; 168 169 /** Element of the list of jobs */ 170 QLIST_ENTRY(Job) job_list; 171 172 /** Transaction this job is part of */ 173 JobTxn *txn; 174 175 /** Element of the list of jobs in a job transaction */ 176 QLIST_ENTRY(Job) txn_list; 177 } Job; 178 179 /** 180 * Callbacks and other information about a Job driver. 181 * All callbacks are invoked with job_mutex *not* held. 182 */ 183 struct JobDriver { 184 185 /* 186 * These fields are initialized when this object is created, 187 * and are never changed afterwards 188 */ 189 190 /** Derived Job struct size */ 191 size_t instance_size; 192 193 /** Enum describing the operation */ 194 JobType job_type; 195 196 /** 197 * Mandatory: Entrypoint for the Coroutine. 198 * 199 * This callback will be invoked when moving from CREATED to RUNNING. 200 * 201 * If this callback returns nonzero, the job transaction it is part of is 202 * aborted. If it returns zero, the job moves into the WAITING state. If it 203 * is the last job to complete in its transaction, all jobs in the 204 * transaction move from WAITING to PENDING. 205 * 206 * This callback must be run in the job's context. 207 */ 208 int coroutine_fn (*run)(Job *job, Error **errp); 209 210 /* 211 * Functions run without regard to the BQL that may run in any 212 * arbitrary thread. These functions do not need to be thread-safe 213 * because the caller ensures that they are invoked from one 214 * thread at time. 215 */ 216 217 /** 218 * If the callback is not NULL, it will be invoked when the job transitions 219 * into the paused state. Paused jobs must not perform any asynchronous 220 * I/O or event loop activity. This callback is used to quiesce jobs. 221 */ 222 void coroutine_fn (*pause)(Job *job); 223 224 /** 225 * If the callback is not NULL, it will be invoked when the job transitions 226 * out of the paused state. Any asynchronous I/O or event loop activity 227 * should be restarted from this callback. 228 */ 229 void coroutine_fn (*resume)(Job *job); 230 231 /* 232 * Global state (GS) API. These functions run under the BQL. 233 * 234 * See include/block/block-global-state.h for more information about 235 * the GS API. 236 */ 237 238 /** 239 * Called when the job is resumed by the user (i.e. user_paused becomes 240 * false). .user_resume is called before .resume. 241 */ 242 void (*user_resume)(Job *job); 243 244 /** 245 * Optional callback for job types whose completion must be triggered 246 * manually. 247 */ 248 void (*complete)(Job *job, Error **errp); 249 250 /** 251 * If the callback is not NULL, prepare will be invoked when all the jobs 252 * belonging to the same transaction complete; or upon this job's completion 253 * if it is not in a transaction. 254 * 255 * This callback will not be invoked if the job has already failed. 256 * If it fails, abort and then clean will be called. 257 */ 258 int (*prepare)(Job *job); 259 260 /** 261 * If the callback is not NULL, it will be invoked when all the jobs 262 * belonging to the same transaction complete; or upon this job's 263 * completion if it is not in a transaction. Skipped if NULL. 264 * 265 * All jobs will complete with a call to either .commit() or .abort() but 266 * never both. 267 */ 268 void (*commit)(Job *job); 269 270 /** 271 * If the callback is not NULL, it will be invoked when any job in the 272 * same transaction fails; or upon this job's failure (due to error or 273 * cancellation) if it is not in a transaction. Skipped if NULL. 274 * 275 * All jobs will complete with a call to either .commit() or .abort() but 276 * never both. 277 */ 278 void (*abort)(Job *job); 279 280 /** 281 * If the callback is not NULL, it will be invoked after a call to either 282 * .commit() or .abort(). Regardless of which callback is invoked after 283 * completion, .clean() will always be called, even if the job does not 284 * belong to a transaction group. 285 */ 286 void (*clean)(Job *job); 287 288 /** 289 * If the callback is not NULL, it will be invoked in job_cancel_async 290 * 291 * This function must return true if the job will be cancelled 292 * immediately without any further I/O (mandatory if @force is 293 * true), and false otherwise. This lets the generic job layer 294 * know whether a job has been truly (force-)cancelled, or whether 295 * it is just in a special completion mode (like mirror after 296 * READY). 297 * (If the callback is NULL, the job is assumed to terminate 298 * without I/O.) 299 */ 300 bool (*cancel)(Job *job, bool force); 301 302 303 /** Called when the job is freed */ 304 void (*free)(Job *job); 305 }; 306 307 typedef enum JobCreateFlags { 308 /* Default behavior */ 309 JOB_DEFAULT = 0x00, 310 /* Job is not QMP-created and should not send QMP events */ 311 JOB_INTERNAL = 0x01, 312 /* Job requires manual finalize step */ 313 JOB_MANUAL_FINALIZE = 0x02, 314 /* Job requires manual dismiss step */ 315 JOB_MANUAL_DISMISS = 0x04, 316 } JobCreateFlags; 317 318 extern QemuMutex job_mutex; 319 320 #define JOB_LOCK_GUARD() /* QEMU_LOCK_GUARD(&job_mutex) */ 321 322 #define WITH_JOB_LOCK_GUARD() /* WITH_QEMU_LOCK_GUARD(&job_mutex) */ 323 324 /** 325 * job_lock: 326 * 327 * Take the mutex protecting the list of jobs and their status. 328 * Most functions called by the monitor need to call job_lock 329 * and job_unlock manually. On the other hand, function called 330 * by the block jobs themselves and by the block layer will take the 331 * lock for you. 332 */ 333 void job_lock(void); 334 335 /** 336 * job_unlock: 337 * 338 * Release the mutex protecting the list of jobs and their status. 339 */ 340 void job_unlock(void); 341 342 /** 343 * Allocate and return a new job transaction. Jobs can be added to the 344 * transaction using job_txn_add_job(). 345 * 346 * The transaction is automatically freed when the last job completes or is 347 * cancelled. 348 * 349 * All jobs in the transaction either complete successfully or fail/cancel as a 350 * group. Jobs wait for each other before completing. Cancelling one job 351 * cancels all jobs in the transaction. 352 */ 353 JobTxn *job_txn_new(void); 354 355 /** 356 * Release a reference that was previously acquired with job_txn_add_job or 357 * job_txn_new. If it's the last reference to the object, it will be freed. 358 */ 359 void job_txn_unref(JobTxn *txn); 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 /** 423 * Conditionally enter the job coroutine if the job is ready to run, not 424 * already busy and fn() returns true. fn() is called while under the job_lock 425 * critical section. 426 */ 427 void job_enter_cond(Job *job, bool(*fn)(Job *job)); 428 429 /** 430 * @job: A job that has not yet been started. 431 * 432 * Begins execution of a job. 433 * Takes ownership of one reference to the job object. 434 */ 435 void job_start(Job *job); 436 437 /** 438 * @job: The job to enter. 439 * 440 * Continue the specified job by entering the coroutine. 441 */ 442 void job_enter(Job *job); 443 444 /** 445 * @job: The job that is ready to pause. 446 * 447 * Pause now if job_pause() has been called. Jobs that perform lots of I/O 448 * must call this between requests so that the job can be paused. 449 */ 450 void coroutine_fn job_pause_point(Job *job); 451 452 /** 453 * @job: The job that calls the function. 454 * 455 * Yield the job coroutine. 456 */ 457 void coroutine_fn job_yield(Job *job); 458 459 /** 460 * @job: The job that calls the function. 461 * @ns: How many nanoseconds to stop for. 462 * 463 * Put the job to sleep (assuming that it wasn't canceled) for @ns 464 * %QEMU_CLOCK_REALTIME nanoseconds. Canceling the job will immediately 465 * interrupt the wait. 466 */ 467 void coroutine_fn job_sleep_ns(Job *job, int64_t ns); 468 469 /** Returns the JobType of a given Job. */ 470 JobType job_type(const Job *job); 471 472 /** Returns the enum string for the JobType of a given Job. */ 473 const char *job_type_str(const Job *job); 474 475 /** Returns true if the job should not be visible to the management layer. */ 476 bool job_is_internal(Job *job); 477 478 /** Returns whether the job is being cancelled. */ 479 bool job_is_cancelled(Job *job); 480 481 /** 482 * Returns whether the job is scheduled for cancellation (at an 483 * indefinite point). 484 */ 485 bool job_cancel_requested(Job *job); 486 487 /** Returns whether the job is in a completed state. */ 488 bool job_is_completed(Job *job); 489 490 /** Returns whether the job is ready to be completed. */ 491 bool job_is_ready(Job *job); 492 493 /** 494 * Request @job to pause at the next pause point. Must be paired with 495 * job_resume(). If the job is supposed to be resumed by user action, call 496 * job_user_pause() instead. 497 */ 498 void job_pause(Job *job); 499 500 /** Resumes a @job paused with job_pause. */ 501 void job_resume(Job *job); 502 503 /** 504 * Asynchronously pause the specified @job. 505 * Do not allow a resume until a matching call to job_user_resume. 506 */ 507 void job_user_pause(Job *job, Error **errp); 508 509 /** Returns true if the job is user-paused. */ 510 bool job_user_paused(Job *job); 511 512 /** 513 * Resume the specified @job. 514 * Must be paired with a preceding job_user_pause. 515 */ 516 void job_user_resume(Job *job, Error **errp); 517 518 /** 519 * Get the next element from the list of block jobs after @job, or the 520 * first one if @job is %NULL. 521 * 522 * Returns the requested job, or %NULL if there are no more jobs left. 523 */ 524 Job *job_next(Job *job); 525 526 /** 527 * Get the job identified by @id (which must not be %NULL). 528 * 529 * Returns the requested job, or %NULL if it doesn't exist. 530 */ 531 Job *job_get(const char *id); 532 533 /** 534 * Check whether the verb @verb can be applied to @job in its current state. 535 * Returns 0 if the verb can be applied; otherwise errp is set and -EPERM 536 * returned. 537 */ 538 int job_apply_verb(Job *job, JobVerb verb, Error **errp); 539 540 /** The @job could not be started, free it. */ 541 void job_early_fail(Job *job); 542 543 /** Moves the @job from RUNNING to READY */ 544 void job_transition_to_ready(Job *job); 545 546 /** Asynchronously complete the specified @job. */ 547 void job_complete(Job *job, Error **errp); 548 549 /** 550 * Asynchronously cancel the specified @job. If @force is true, the job should 551 * be cancelled immediately without waiting for a consistent state. 552 */ 553 void job_cancel(Job *job, bool force); 554 555 /** 556 * Cancels the specified job like job_cancel(), but may refuse to do so if the 557 * operation isn't meaningful in the current state of the job. 558 */ 559 void job_user_cancel(Job *job, bool force, Error **errp); 560 561 /** 562 * Synchronously cancel the @job. The completion callback is called 563 * before the function returns. If @force is false, the job may 564 * actually complete instead of canceling itself; the circumstances 565 * under which this happens depend on the kind of job that is active. 566 * 567 * Returns the return value from the job if the job actually completed 568 * during the call, or -ECANCELED if it was canceled. 569 * 570 * Callers must hold the AioContext lock of job->aio_context. 571 */ 572 int job_cancel_sync(Job *job, bool force); 573 574 /** Synchronously force-cancels all jobs using job_cancel_sync(). */ 575 void job_cancel_sync_all(void); 576 577 /** 578 * @job: The job to be completed. 579 * @errp: Error object which may be set by job_complete(); this is not 580 * necessarily set on every error, the job return value has to be 581 * checked as well. 582 * 583 * Synchronously complete the job. The completion callback is called before the 584 * function returns, unless it is NULL (which is permissible when using this 585 * function). 586 * 587 * Returns the return value from the job. 588 * 589 * Callers must hold the AioContext lock of job->aio_context. 590 */ 591 int job_complete_sync(Job *job, Error **errp); 592 593 /** 594 * For a @job that has finished its work and is pending awaiting explicit 595 * acknowledgement to commit its work, this will commit that work. 596 * 597 * FIXME: Make the below statement universally true: 598 * For jobs that support the manual workflow mode, all graph changes that occur 599 * as a result will occur after this command and before a successful reply. 600 */ 601 void job_finalize(Job *job, Error **errp); 602 603 /** 604 * Remove the concluded @job from the query list and resets the passed pointer 605 * to %NULL. Returns an error if the job is not actually concluded. 606 */ 607 void job_dismiss(Job **job, Error **errp); 608 609 /** 610 * Synchronously finishes the given @job. If @finish is given, it is called to 611 * trigger completion or cancellation of the job. 612 * 613 * Returns 0 if the job is successfully completed, -ECANCELED if the job was 614 * cancelled before completing, and -errno in other error cases. 615 * 616 * Callers must hold the AioContext lock of job->aio_context. 617 */ 618 int job_finish_sync(Job *job, void (*finish)(Job *, Error **errp), Error **errp); 619 620 #endif 621