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 bool busy; 81 82 /** 83 * Set to true by the job while it is in a quiescent state, where 84 * no I/O or event loop activity is pending. 85 */ 86 bool paused; 87 88 /** 89 * Set to true if the job is paused by user. Can be unpaused with the 90 * block-job-resume QMP command. 91 */ 92 bool user_paused; 93 94 /** 95 * Set to true if the job should cancel itself. The flag must 96 * always be tested just before toggling the busy flag from false 97 * to true. After a job has been cancelled, it should only yield 98 * if #aio_poll will ("sooner or later") reenter the coroutine. 99 */ 100 bool cancelled; 101 102 /** 103 * Set to true if the job should abort immediately without waiting 104 * for data to be in sync. 105 */ 106 bool force_cancel; 107 108 /** Set to true when the job has deferred work to the main loop. */ 109 bool deferred_to_main_loop; 110 111 /** True if this job should automatically finalize itself */ 112 bool auto_finalize; 113 114 /** True if this job should automatically dismiss itself */ 115 bool auto_dismiss; 116 117 /** 118 * Current progress. The unit is arbitrary as long as the ratio between 119 * progress_current and progress_total represents the estimated percentage 120 * of work already done. 121 */ 122 int64_t progress_current; 123 124 /** Estimated progress_current value at the completion of the job */ 125 int64_t progress_total; 126 127 /** Error string for a failed job (NULL if, and only if, job->ret == 0) */ 128 char *error; 129 130 /** ret code passed to job_completed. */ 131 int ret; 132 133 /** The completion function that will be called when the job completes. */ 134 BlockCompletionFunc *cb; 135 136 /** The opaque value that is passed to the completion function. */ 137 void *opaque; 138 139 /** Notifiers called when a cancelled job is finalised */ 140 NotifierList on_finalize_cancelled; 141 142 /** Notifiers called when a successfully completed job is finalised */ 143 NotifierList on_finalize_completed; 144 145 /** Notifiers called when the job transitions to PENDING */ 146 NotifierList on_pending; 147 148 /** Notifiers called when the job transitions to READY */ 149 NotifierList on_ready; 150 151 /** Element of the list of jobs */ 152 QLIST_ENTRY(Job) job_list; 153 154 /** Transaction this job is part of */ 155 JobTxn *txn; 156 157 /** Element of the list of jobs in a job transaction */ 158 QLIST_ENTRY(Job) txn_list; 159} Job; 160 161/** 162 * Callbacks and other information about a Job driver. 163 */ 164struct JobDriver { 165 /** Derived Job struct size */ 166 size_t instance_size; 167 168 /** Enum describing the operation */ 169 JobType job_type; 170 171 /** Mandatory: Entrypoint for the Coroutine. */ 172 CoroutineEntry *start; 173 174 /** 175 * If the callback is not NULL, it will be invoked when the job transitions 176 * into the paused state. Paused jobs must not perform any asynchronous 177 * I/O or event loop activity. This callback is used to quiesce jobs. 178 */ 179 void coroutine_fn (*pause)(Job *job); 180 181 /** 182 * If the callback is not NULL, it will be invoked when the job transitions 183 * out of the paused state. Any asynchronous I/O or event loop activity 184 * should be restarted from this callback. 185 */ 186 void coroutine_fn (*resume)(Job *job); 187 188 /** 189 * Called when the job is resumed by the user (i.e. user_paused becomes 190 * false). .user_resume is called before .resume. 191 */ 192 void (*user_resume)(Job *job); 193 194 /** 195 * Optional callback for job types whose completion must be triggered 196 * manually. 197 */ 198 void (*complete)(Job *job, Error **errp); 199 200 /* 201 * If the callback is not NULL, it will be invoked when the job has to be 202 * synchronously cancelled or completed; it should drain any activities 203 * as required to ensure progress. 204 */ 205 void (*drain)(Job *job); 206 207 /** 208 * If the callback is not NULL, prepare will be invoked when all the jobs 209 * belonging to the same transaction complete; or upon this job's completion 210 * if it is not in a transaction. 211 * 212 * This callback will not be invoked if the job has already failed. 213 * If it fails, abort and then clean will be called. 214 */ 215 int (*prepare)(Job *job); 216 217 /** 218 * If the callback is not NULL, it will be invoked when all the jobs 219 * belonging to the same transaction complete; or upon this job's 220 * completion if it is not in a transaction. Skipped if NULL. 221 * 222 * All jobs will complete with a call to either .commit() or .abort() but 223 * never both. 224 */ 225 void (*commit)(Job *job); 226 227 /** 228 * If the callback is not NULL, it will be invoked when any job in the 229 * same transaction fails; or upon this job's failure (due to error or 230 * cancellation) if it is not in a transaction. Skipped if NULL. 231 * 232 * All jobs will complete with a call to either .commit() or .abort() but 233 * never both. 234 */ 235 void (*abort)(Job *job); 236 237 /** 238 * If the callback is not NULL, it will be invoked after a call to either 239 * .commit() or .abort(). Regardless of which callback is invoked after 240 * completion, .clean() will always be called, even if the job does not 241 * belong to a transaction group. 242 */ 243 void (*clean)(Job *job); 244 245 246 /** Called when the job is freed */ 247 void (*free)(Job *job); 248}; 249 250typedef enum JobCreateFlags { 251 /* Default behavior */ 252 JOB_DEFAULT = 0x00, 253 /* Job is not QMP-created and should not send QMP events */ 254 JOB_INTERNAL = 0x01, 255 /* Job requires manual finalize step */ 256 JOB_MANUAL_FINALIZE = 0x02, 257 /* Job requires manual dismiss step */ 258 JOB_MANUAL_DISMISS = 0x04, 259} JobCreateFlags; 260 261/** 262 * Allocate and return a new job transaction. Jobs can be added to the 263 * transaction using job_txn_add_job(). 264 * 265 * The transaction is automatically freed when the last job completes or is 266 * cancelled. 267 * 268 * All jobs in the transaction either complete successfully or fail/cancel as a 269 * group. Jobs wait for each other before completing. Cancelling one job 270 * cancels all jobs in the transaction. 271 */ 272JobTxn *job_txn_new(void); 273 274/** 275 * Release a reference that was previously acquired with job_txn_add_job or 276 * job_txn_new. If it's the last reference to the object, it will be freed. 277 */ 278void job_txn_unref(JobTxn *txn); 279 280/** 281 * @txn: The transaction (may be NULL) 282 * @job: Job to add to the transaction 283 * 284 * Add @job to the transaction. The @job must not already be in a transaction. 285 * The caller must call either job_txn_unref() or job_completed() to release 286 * the reference that is automatically grabbed here. 287 * 288 * If @txn is NULL, the function does nothing. 289 */ 290void job_txn_add_job(JobTxn *txn, Job *job); 291 292/** 293 * Create a new long-running job and return it. 294 * 295 * @job_id: The id of the newly-created job, or %NULL for internal jobs 296 * @driver: The class object for the newly-created job. 297 * @txn: The transaction this job belongs to, if any. %NULL otherwise. 298 * @ctx: The AioContext to run the job coroutine in. 299 * @flags: Creation flags for the job. See @JobCreateFlags. 300 * @cb: Completion function for the job. 301 * @opaque: Opaque pointer value passed to @cb. 302 * @errp: Error object. 303 */ 304void *job_create(const char *job_id, const JobDriver *driver, JobTxn *txn, 305 AioContext *ctx, int flags, BlockCompletionFunc *cb, 306 void *opaque, Error **errp); 307 308/** 309 * Add a reference to Job refcnt, it will be decreased with job_unref, and then 310 * be freed if it comes to be the last reference. 311 */ 312void job_ref(Job *job); 313 314/** 315 * Release a reference that was previously acquired with job_ref() or 316 * job_create(). If it's the last reference to the object, it will be freed. 317 */ 318void job_unref(Job *job); 319 320/** 321 * @job: The job that has made progress 322 * @done: How much progress the job made since the last call 323 * 324 * Updates the progress counter of the job. 325 */ 326void job_progress_update(Job *job, uint64_t done); 327 328/** 329 * @job: The job whose expected progress end value is set 330 * @remaining: Missing progress (on top of the current progress counter value) 331 * until the new expected end value is reached 332 * 333 * Sets the expected end value of the progress counter of a job so that a 334 * completion percentage can be calculated when the progress is updated. 335 */ 336void job_progress_set_remaining(Job *job, uint64_t remaining); 337 338/** 339 * @job: The job whose expected progress end value is updated 340 * @delta: Value which is to be added to the current expected end 341 * value 342 * 343 * Increases the expected end value of the progress counter of a job. 344 * This is useful for parenthesis operations: If a job has to 345 * conditionally perform a high-priority operation as part of its 346 * progress, it calls this function with the expected operation's 347 * length before, and job_progress_update() afterwards. 348 * (So the operation acts as a parenthesis in regards to the main job 349 * operation running in background.) 350 */ 351void job_progress_increase_remaining(Job *job, uint64_t delta); 352 353/** To be called when a cancelled job is finalised. */ 354void job_event_cancelled(Job *job); 355 356/** To be called when a successfully completed job is finalised. */ 357void job_event_completed(Job *job); 358 359/** 360 * Conditionally enter the job coroutine if the job is ready to run, not 361 * already busy and fn() returns true. fn() is called while under the job_lock 362 * critical section. 363 */ 364void job_enter_cond(Job *job, bool(*fn)(Job *job)); 365 366/** 367 * @job: A job that has not yet been started. 368 * 369 * Begins execution of a job. 370 * Takes ownership of one reference to the job object. 371 */ 372void job_start(Job *job); 373 374/** 375 * @job: The job to enter. 376 * 377 * Continue the specified job by entering the coroutine. 378 */ 379void job_enter(Job *job); 380 381/** 382 * @job: The job that is ready to pause. 383 * 384 * Pause now if job_pause() has been called. Jobs that perform lots of I/O 385 * must call this between requests so that the job can be paused. 386 */ 387void coroutine_fn job_pause_point(Job *job); 388 389/** 390 * @job: The job that calls the function. 391 * 392 * Yield the job coroutine. 393 */ 394void job_yield(Job *job); 395 396/** 397 * @job: The job that calls the function. 398 * @ns: How many nanoseconds to stop for. 399 * 400 * Put the job to sleep (assuming that it wasn't canceled) for @ns 401 * %QEMU_CLOCK_REALTIME nanoseconds. Canceling the job will immediately 402 * interrupt the wait. 403 */ 404void coroutine_fn job_sleep_ns(Job *job, int64_t ns); 405 406 407/** Returns the JobType of a given Job. */ 408JobType job_type(const Job *job); 409 410/** Returns the enum string for the JobType of a given Job. */ 411const char *job_type_str(const Job *job); 412 413/** Returns true if the job should not be visible to the management layer. */ 414bool job_is_internal(Job *job); 415 416/** Returns whether the job is scheduled for cancellation. */ 417bool job_is_cancelled(Job *job); 418 419/** Returns whether the job is in a completed state. */ 420bool job_is_completed(Job *job); 421 422/** Returns whether the job is ready to be completed. */ 423bool job_is_ready(Job *job); 424 425/** 426 * Request @job to pause at the next pause point. Must be paired with 427 * job_resume(). If the job is supposed to be resumed by user action, call 428 * job_user_pause() instead. 429 */ 430void job_pause(Job *job); 431 432/** Resumes a @job paused with job_pause. */ 433void job_resume(Job *job); 434 435/** 436 * Asynchronously pause the specified @job. 437 * Do not allow a resume until a matching call to job_user_resume. 438 */ 439void job_user_pause(Job *job, Error **errp); 440 441/** Returns true if the job is user-paused. */ 442bool job_user_paused(Job *job); 443 444/** 445 * Resume the specified @job. 446 * Must be paired with a preceding job_user_pause. 447 */ 448void job_user_resume(Job *job, Error **errp); 449 450/* 451 * Drain any activities as required to ensure progress. This can be called in a 452 * loop to synchronously complete a job. 453 */ 454void job_drain(Job *job); 455 456/** 457 * Get the next element from the list of block jobs after @job, or the 458 * first one if @job is %NULL. 459 * 460 * Returns the requested job, or %NULL if there are no more jobs left. 461 */ 462Job *job_next(Job *job); 463 464/** 465 * Get the job identified by @id (which must not be %NULL). 466 * 467 * Returns the requested job, or %NULL if it doesn't exist. 468 */ 469Job *job_get(const char *id); 470 471/** 472 * Check whether the verb @verb can be applied to @job in its current state. 473 * Returns 0 if the verb can be applied; otherwise errp is set and -EPERM 474 * returned. 475 */ 476int job_apply_verb(Job *job, JobVerb verb, Error **errp); 477 478/** The @job could not be started, free it. */ 479void job_early_fail(Job *job); 480 481/** Moves the @job from RUNNING to READY */ 482void job_transition_to_ready(Job *job); 483 484/** 485 * @job: The job being completed. 486 * @ret: The status code. 487 * @error: The error message for a failing job (only with @ret < 0). If @ret is 488 * negative, but NULL is given for @error, strerror() is used. 489 * 490 * Marks @job as completed. If @ret is non-zero, the job transaction it is part 491 * of is aborted. If @ret is zero, the job moves into the WAITING state. If it 492 * is the last job to complete in its transaction, all jobs in the transaction 493 * move from WAITING to PENDING. 494 */ 495void job_completed(Job *job, int ret, Error *error); 496 497/** Asynchronously complete the specified @job. */ 498void job_complete(Job *job, Error **errp); 499 500/** 501 * Asynchronously cancel the specified @job. If @force is true, the job should 502 * be cancelled immediately without waiting for a consistent state. 503 */ 504void job_cancel(Job *job, bool force); 505 506/** 507 * Cancels the specified job like job_cancel(), but may refuse to do so if the 508 * operation isn't meaningful in the current state of the job. 509 */ 510void job_user_cancel(Job *job, bool force, Error **errp); 511 512/** 513 * Synchronously cancel the @job. The completion callback is called 514 * before the function returns. The job may actually complete 515 * instead of canceling itself; the circumstances under which this 516 * happens depend on the kind of job that is active. 517 * 518 * Returns the return value from the job if the job actually completed 519 * during the call, or -ECANCELED if it was canceled. 520 */ 521int job_cancel_sync(Job *job); 522 523/** Synchronously cancels all jobs using job_cancel_sync(). */ 524void job_cancel_sync_all(void); 525 526/** 527 * @job: The job to be completed. 528 * @errp: Error object which may be set by job_complete(); this is not 529 * necessarily set on every error, the job return value has to be 530 * checked as well. 531 * 532 * Synchronously complete the job. The completion callback is called before the 533 * function returns, unless it is NULL (which is permissible when using this 534 * function). 535 * 536 * Returns the return value from the job. 537 */ 538int job_complete_sync(Job *job, Error **errp); 539 540/** 541 * For a @job that has finished its work and is pending awaiting explicit 542 * acknowledgement to commit its work, this will commit that work. 543 * 544 * FIXME: Make the below statement universally true: 545 * For jobs that support the manual workflow mode, all graph changes that occur 546 * as a result will occur after this command and before a successful reply. 547 */ 548void job_finalize(Job *job, Error **errp); 549 550/** 551 * Remove the concluded @job from the query list and resets the passed pointer 552 * to %NULL. Returns an error if the job is not actually concluded. 553 */ 554void job_dismiss(Job **job, Error **errp); 555 556typedef void JobDeferToMainLoopFn(Job *job, void *opaque); 557 558/** 559 * @job: The job 560 * @fn: The function to run in the main loop 561 * @opaque: The opaque value that is passed to @fn 562 * 563 * This function must be called by the main job coroutine just before it 564 * returns. @fn is executed in the main loop with the job AioContext acquired. 565 * 566 * Block jobs must call bdrv_unref(), bdrv_close(), and anything that uses 567 * bdrv_drain_all() in the main loop. 568 * 569 * The @job AioContext is held while @fn executes. 570 */ 571void job_defer_to_main_loop(Job *job, JobDeferToMainLoopFn *fn, void *opaque); 572 573/** 574 * Synchronously finishes the given @job. If @finish is given, it is called to 575 * trigger completion or cancellation of the job. 576 * 577 * Returns 0 if the job is successfully completed, -ECANCELED if the job was 578 * cancelled before completing, and -errno in other error cases. 579 */ 580int job_finish_sync(Job *job, void (*finish)(Job *, Error **errp), Error **errp); 581 582#endif 583