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