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