133e9e9bdSKevin Wolf /* 233e9e9bdSKevin Wolf * Declarations for background jobs 333e9e9bdSKevin Wolf * 433e9e9bdSKevin Wolf * Copyright (c) 2011 IBM Corp. 533e9e9bdSKevin Wolf * Copyright (c) 2012, 2018 Red Hat, Inc. 633e9e9bdSKevin Wolf * 733e9e9bdSKevin Wolf * Permission is hereby granted, free of charge, to any person obtaining a copy 833e9e9bdSKevin Wolf * of this software and associated documentation files (the "Software"), to deal 933e9e9bdSKevin Wolf * in the Software without restriction, including without limitation the rights 1033e9e9bdSKevin Wolf * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 1133e9e9bdSKevin Wolf * copies of the Software, and to permit persons to whom the Software is 1233e9e9bdSKevin Wolf * furnished to do so, subject to the following conditions: 1333e9e9bdSKevin Wolf * 1433e9e9bdSKevin Wolf * The above copyright notice and this permission notice shall be included in 1533e9e9bdSKevin Wolf * all copies or substantial portions of the Software. 1633e9e9bdSKevin Wolf * 1733e9e9bdSKevin Wolf * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 1833e9e9bdSKevin Wolf * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 1933e9e9bdSKevin Wolf * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 2033e9e9bdSKevin Wolf * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 2133e9e9bdSKevin Wolf * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 2233e9e9bdSKevin Wolf * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 2333e9e9bdSKevin Wolf * THE SOFTWARE. 2433e9e9bdSKevin Wolf */ 2533e9e9bdSKevin Wolf 2633e9e9bdSKevin Wolf #ifndef JOB_H 2733e9e9bdSKevin Wolf #define JOB_H 2833e9e9bdSKevin Wolf 292ae16a6aSMarkus Armbruster #include "qapi/qapi-types-job.h" 30e7c1d78bSKevin Wolf #include "qemu/queue.h" 3101fe1ca9SVladimir Sementsov-Ogievskiy #include "qemu/progress_meter.h" 32da01ff7fSKevin Wolf #include "qemu/coroutine.h" 334ad35181SKevin Wolf #include "block/aio.h" 34252291eaSKevin Wolf 3533e9e9bdSKevin Wolf typedef struct JobDriver JobDriver; 367eaa8fb5SKevin Wolf typedef struct JobTxn JobTxn; 377eaa8fb5SKevin Wolf 3833e9e9bdSKevin Wolf 3933e9e9bdSKevin Wolf /** 4033e9e9bdSKevin Wolf * Long-running operation. 4133e9e9bdSKevin Wolf */ 4233e9e9bdSKevin Wolf typedef struct Job { 43d08f0754SEmanuele Giuseppe Esposito 44d08f0754SEmanuele Giuseppe Esposito /* Fields set at initialization (job_create), and never modified */ 45d08f0754SEmanuele Giuseppe Esposito 4633e9e9bdSKevin Wolf /** The ID of the job. May be NULL for internal jobs. */ 4733e9e9bdSKevin Wolf char *id; 4833e9e9bdSKevin Wolf 49d08f0754SEmanuele Giuseppe Esposito /** 50d08f0754SEmanuele Giuseppe Esposito * The type of this job. 51d08f0754SEmanuele Giuseppe Esposito * All callbacks are called with job_mutex *not* held. 52d08f0754SEmanuele Giuseppe Esposito */ 5333e9e9bdSKevin Wolf const JobDriver *driver; 54e7c1d78bSKevin Wolf 55d08f0754SEmanuele Giuseppe Esposito /** 56d08f0754SEmanuele Giuseppe Esposito * The coroutine that executes the job. If not NULL, it is reentered when 57d08f0754SEmanuele Giuseppe Esposito * busy is false and the job is cancelled. 58d08f0754SEmanuele Giuseppe Esposito * Initialized in job_start() 59d08f0754SEmanuele Giuseppe Esposito */ 60d08f0754SEmanuele Giuseppe Esposito Coroutine *co; 61d08f0754SEmanuele Giuseppe Esposito 62d08f0754SEmanuele Giuseppe Esposito /** True if this job should automatically finalize itself */ 63d08f0754SEmanuele Giuseppe Esposito bool auto_finalize; 64d08f0754SEmanuele Giuseppe Esposito 65d08f0754SEmanuele Giuseppe Esposito /** True if this job should automatically dismiss itself */ 66d08f0754SEmanuele Giuseppe Esposito bool auto_dismiss; 67d08f0754SEmanuele Giuseppe Esposito 682fc3bdc3SEmanuele Giuseppe Esposito /** 692fc3bdc3SEmanuele Giuseppe Esposito * The completion function that will be called when the job completes. 702fc3bdc3SEmanuele Giuseppe Esposito * Called with AioContext lock held, since many callback implementations 712fc3bdc3SEmanuele Giuseppe Esposito * use bdrv_* functions that require to hold the lock. 722fc3bdc3SEmanuele Giuseppe Esposito */ 73d08f0754SEmanuele Giuseppe Esposito BlockCompletionFunc *cb; 74d08f0754SEmanuele Giuseppe Esposito 75d08f0754SEmanuele Giuseppe Esposito /** The opaque value that is passed to the completion function. */ 76d08f0754SEmanuele Giuseppe Esposito void *opaque; 77d08f0754SEmanuele Giuseppe Esposito 78d08f0754SEmanuele Giuseppe Esposito /* ProgressMeter API is thread-safe */ 79d08f0754SEmanuele Giuseppe Esposito ProgressMeter progress; 80d08f0754SEmanuele Giuseppe Esposito 813ed4f708SEmanuele Giuseppe Esposito /** 823ed4f708SEmanuele Giuseppe Esposito * AioContext to run the job coroutine in. 833ed4f708SEmanuele Giuseppe Esposito * The job Aiocontext can be read when holding *either* 843ed4f708SEmanuele Giuseppe Esposito * the BQL (so we are in the main loop) or the job_mutex. 853ed4f708SEmanuele Giuseppe Esposito * It can only be written when we hold *both* BQL 863ed4f708SEmanuele Giuseppe Esposito * and the job_mutex. 873ed4f708SEmanuele Giuseppe Esposito */ 883ed4f708SEmanuele Giuseppe Esposito AioContext *aio_context; 893ed4f708SEmanuele Giuseppe Esposito 90d08f0754SEmanuele Giuseppe Esposito 916f592e5aSEmanuele Giuseppe Esposito /** Protected by job_mutex */ 92d08f0754SEmanuele Giuseppe Esposito 9380fa2c75SKevin Wolf /** Reference count of the block job */ 9480fa2c75SKevin Wolf int refcnt; 9580fa2c75SKevin Wolf 96a50c2ab8SKevin Wolf /** Current state; See @JobStatus for details. */ 97a50c2ab8SKevin Wolf JobStatus status; 98a50c2ab8SKevin Wolf 99da01ff7fSKevin Wolf /** 1005d43e86eSKevin Wolf * Timer that is used by @job_sleep_ns. Accessed under job_mutex (in 101da01ff7fSKevin Wolf * job.c). 102da01ff7fSKevin Wolf */ 103da01ff7fSKevin Wolf QEMUTimer sleep_timer; 104da01ff7fSKevin Wolf 105da01ff7fSKevin Wolf /** 106da01ff7fSKevin Wolf * Counter for pause request. If non-zero, the block job is either paused, 107da01ff7fSKevin Wolf * or if busy == true will pause itself as soon as possible. 108da01ff7fSKevin Wolf */ 109da01ff7fSKevin Wolf int pause_count; 110da01ff7fSKevin Wolf 111da01ff7fSKevin Wolf /** 112da01ff7fSKevin Wolf * Set to false by the job while the coroutine has yielded and may be 1133d70ff53SKevin Wolf * re-entered by job_enter(). There may still be I/O or event loop activity 1146f592e5aSEmanuele Giuseppe Esposito * pending. Accessed under job_mutex. 115b5a7a057SKevin Wolf * 116b5a7a057SKevin Wolf * When the job is deferred to the main loop, busy is true as long as the 117b5a7a057SKevin Wolf * bottom half is still pending. 118da01ff7fSKevin Wolf */ 119da01ff7fSKevin Wolf bool busy; 120da01ff7fSKevin Wolf 121da01ff7fSKevin Wolf /** 122da01ff7fSKevin Wolf * Set to true by the job while it is in a quiescent state, where 123da01ff7fSKevin Wolf * no I/O or event loop activity is pending. 124da01ff7fSKevin Wolf */ 125da01ff7fSKevin Wolf bool paused; 126da01ff7fSKevin Wolf 127da01ff7fSKevin Wolf /** 128b15de828SKevin Wolf * Set to true if the job is paused by user. Can be unpaused with the 129b15de828SKevin Wolf * block-job-resume QMP command. 130b15de828SKevin Wolf */ 131b15de828SKevin Wolf bool user_paused; 132b15de828SKevin Wolf 133b15de828SKevin Wolf /** 134daa7f2f9SKevin Wolf * Set to true if the job should cancel itself. The flag must 135daa7f2f9SKevin Wolf * always be tested just before toggling the busy flag from false 136daa7f2f9SKevin Wolf * to true. After a job has been cancelled, it should only yield 137daa7f2f9SKevin Wolf * if #aio_poll will ("sooner or later") reenter the coroutine. 138daa7f2f9SKevin Wolf */ 139daa7f2f9SKevin Wolf bool cancelled; 140daa7f2f9SKevin Wolf 141004e95dfSKevin Wolf /** 142004e95dfSKevin Wolf * Set to true if the job should abort immediately without waiting 143004e95dfSKevin Wolf * for data to be in sync. 144004e95dfSKevin Wolf */ 145004e95dfSKevin Wolf bool force_cancel; 146004e95dfSKevin Wolf 1471908a559SKevin Wolf /** Set to true when the job has deferred work to the main loop. */ 1481908a559SKevin Wolf bool deferred_to_main_loop; 1491908a559SKevin Wolf 150404ff28dSJohn Snow /** 151404ff28dSJohn Snow * Return code from @run and/or @prepare callback(s). 152404ff28dSJohn Snow * Not final until the job has reached the CONCLUDED status. 153404ff28dSJohn Snow * 0 on success, -errno on failure. 154404ff28dSJohn Snow */ 1554ad35181SKevin Wolf int ret; 1564ad35181SKevin Wolf 1573d1f8b07SJohn Snow /** 1583d1f8b07SJohn Snow * Error object for a failed job. 1593d1f8b07SJohn Snow * If job->ret is nonzero and an error object was not set, it will be set 1603d1f8b07SJohn Snow * to strerror(-job->ret) during job_completed. 1613d1f8b07SJohn Snow */ 1623d1f8b07SJohn Snow Error *err; 1633d1f8b07SJohn Snow 164139a9f02SKevin Wolf /** Notifiers called when a cancelled job is finalised */ 165139a9f02SKevin Wolf NotifierList on_finalize_cancelled; 166139a9f02SKevin Wolf 167139a9f02SKevin Wolf /** Notifiers called when a successfully completed job is finalised */ 168139a9f02SKevin Wolf NotifierList on_finalize_completed; 169139a9f02SKevin Wolf 170139a9f02SKevin Wolf /** Notifiers called when the job transitions to PENDING */ 171139a9f02SKevin Wolf NotifierList on_pending; 172139a9f02SKevin Wolf 1732e1795b5SKevin Wolf /** Notifiers called when the job transitions to READY */ 1742e1795b5SKevin Wolf NotifierList on_ready; 1752e1795b5SKevin Wolf 17634dc97b9SKevin Wolf /** Notifiers called when the job coroutine yields or terminates */ 17734dc97b9SKevin Wolf NotifierList on_idle; 17834dc97b9SKevin Wolf 179e7c1d78bSKevin Wolf /** Element of the list of jobs */ 180e7c1d78bSKevin Wolf QLIST_ENTRY(Job) job_list; 18162c9e416SKevin Wolf 1827eaa8fb5SKevin Wolf /** Transaction this job is part of */ 1837eaa8fb5SKevin Wolf JobTxn *txn; 1847eaa8fb5SKevin Wolf 18562c9e416SKevin Wolf /** Element of the list of jobs in a job transaction */ 18662c9e416SKevin Wolf QLIST_ENTRY(Job) txn_list; 18733e9e9bdSKevin Wolf } Job; 18833e9e9bdSKevin Wolf 18933e9e9bdSKevin Wolf /** 19033e9e9bdSKevin Wolf * Callbacks and other information about a Job driver. 191d08f0754SEmanuele Giuseppe Esposito * All callbacks are invoked with job_mutex *not* held. 19233e9e9bdSKevin Wolf */ 19333e9e9bdSKevin Wolf struct JobDriver { 19432498092SEmanuele Giuseppe Esposito 19532498092SEmanuele Giuseppe Esposito /* 19632498092SEmanuele Giuseppe Esposito * These fields are initialized when this object is created, 19732498092SEmanuele Giuseppe Esposito * and are never changed afterwards 19832498092SEmanuele Giuseppe Esposito */ 19932498092SEmanuele Giuseppe Esposito 20033e9e9bdSKevin Wolf /** Derived Job struct size */ 20133e9e9bdSKevin Wolf size_t instance_size; 202252291eaSKevin Wolf 203252291eaSKevin Wolf /** Enum describing the operation */ 204252291eaSKevin Wolf JobType job_type; 20580fa2c75SKevin Wolf 206404ff28dSJohn Snow /** 207404ff28dSJohn Snow * Mandatory: Entrypoint for the Coroutine. 208404ff28dSJohn Snow * 209404ff28dSJohn Snow * This callback will be invoked when moving from CREATED to RUNNING. 210404ff28dSJohn Snow * 211404ff28dSJohn Snow * If this callback returns nonzero, the job transaction it is part of is 212404ff28dSJohn Snow * aborted. If it returns zero, the job moves into the WAITING state. If it 213404ff28dSJohn Snow * is the last job to complete in its transaction, all jobs in the 214404ff28dSJohn Snow * transaction move from WAITING to PENDING. 21532498092SEmanuele Giuseppe Esposito * 21632498092SEmanuele Giuseppe Esposito * This callback must be run in the job's context. 217404ff28dSJohn Snow */ 218f67432a2SJohn Snow int coroutine_fn (*run)(Job *job, Error **errp); 219da01ff7fSKevin Wolf 22032498092SEmanuele Giuseppe Esposito /* 22132498092SEmanuele Giuseppe Esposito * Functions run without regard to the BQL that may run in any 22232498092SEmanuele Giuseppe Esposito * arbitrary thread. These functions do not need to be thread-safe 22332498092SEmanuele Giuseppe Esposito * because the caller ensures that they are invoked from one 22432498092SEmanuele Giuseppe Esposito * thread at time. 22532498092SEmanuele Giuseppe Esposito */ 22632498092SEmanuele Giuseppe Esposito 227da01ff7fSKevin Wolf /** 228da01ff7fSKevin Wolf * If the callback is not NULL, it will be invoked when the job transitions 229da01ff7fSKevin Wolf * into the paused state. Paused jobs must not perform any asynchronous 230da01ff7fSKevin Wolf * I/O or event loop activity. This callback is used to quiesce jobs. 231da01ff7fSKevin Wolf */ 232da01ff7fSKevin Wolf void coroutine_fn (*pause)(Job *job); 233da01ff7fSKevin Wolf 234da01ff7fSKevin Wolf /** 235da01ff7fSKevin Wolf * If the callback is not NULL, it will be invoked when the job transitions 236da01ff7fSKevin Wolf * out of the paused state. Any asynchronous I/O or event loop activity 237da01ff7fSKevin Wolf * should be restarted from this callback. 238da01ff7fSKevin Wolf */ 239da01ff7fSKevin Wolf void coroutine_fn (*resume)(Job *job); 240da01ff7fSKevin Wolf 24132498092SEmanuele Giuseppe Esposito /* 24232498092SEmanuele Giuseppe Esposito * Global state (GS) API. These functions run under the BQL. 24332498092SEmanuele Giuseppe Esposito * 24432498092SEmanuele Giuseppe Esposito * See include/block/block-global-state.h for more information about 24532498092SEmanuele Giuseppe Esposito * the GS API. 24632498092SEmanuele Giuseppe Esposito */ 24732498092SEmanuele Giuseppe Esposito 248b15de828SKevin Wolf /** 249b15de828SKevin Wolf * Called when the job is resumed by the user (i.e. user_paused becomes 250b15de828SKevin Wolf * false). .user_resume is called before .resume. 251b15de828SKevin Wolf */ 252b15de828SKevin Wolf void (*user_resume)(Job *job); 253b15de828SKevin Wolf 2543453d972SKevin Wolf /** 2553453d972SKevin Wolf * Optional callback for job types whose completion must be triggered 2563453d972SKevin Wolf * manually. 2573453d972SKevin Wolf */ 2583453d972SKevin Wolf void (*complete)(Job *job, Error **errp); 2593453d972SKevin Wolf 2604ad35181SKevin Wolf /** 2617eaa8fb5SKevin Wolf * If the callback is not NULL, prepare will be invoked when all the jobs 2627eaa8fb5SKevin Wolf * belonging to the same transaction complete; or upon this job's completion 2637eaa8fb5SKevin Wolf * if it is not in a transaction. 2647eaa8fb5SKevin Wolf * 2657eaa8fb5SKevin Wolf * This callback will not be invoked if the job has already failed. 2667eaa8fb5SKevin Wolf * If it fails, abort and then clean will be called. 2672fc3bdc3SEmanuele Giuseppe Esposito * 2682fc3bdc3SEmanuele Giuseppe Esposito * Called with AioContext lock held, since many callbacs implementations 2692fc3bdc3SEmanuele Giuseppe Esposito * use bdrv_* functions that require to hold the lock. 2707eaa8fb5SKevin Wolf */ 2717eaa8fb5SKevin Wolf int (*prepare)(Job *job); 2727eaa8fb5SKevin Wolf 2737eaa8fb5SKevin Wolf /** 2744ad35181SKevin Wolf * If the callback is not NULL, it will be invoked when all the jobs 2754ad35181SKevin Wolf * belonging to the same transaction complete; or upon this job's 2764ad35181SKevin Wolf * completion if it is not in a transaction. Skipped if NULL. 2774ad35181SKevin Wolf * 2784ad35181SKevin Wolf * All jobs will complete with a call to either .commit() or .abort() but 2794ad35181SKevin Wolf * never both. 2802fc3bdc3SEmanuele Giuseppe Esposito * 2812fc3bdc3SEmanuele Giuseppe Esposito * Called with AioContext lock held, since many callback implementations 2822fc3bdc3SEmanuele Giuseppe Esposito * use bdrv_* functions that require to hold the lock. 2834ad35181SKevin Wolf */ 2844ad35181SKevin Wolf void (*commit)(Job *job); 2854ad35181SKevin Wolf 2864ad35181SKevin Wolf /** 2874ad35181SKevin Wolf * If the callback is not NULL, it will be invoked when any job in the 2884ad35181SKevin Wolf * same transaction fails; or upon this job's failure (due to error or 2894ad35181SKevin Wolf * cancellation) if it is not in a transaction. Skipped if NULL. 2904ad35181SKevin Wolf * 2914ad35181SKevin Wolf * All jobs will complete with a call to either .commit() or .abort() but 2924ad35181SKevin Wolf * never both. 2932fc3bdc3SEmanuele Giuseppe Esposito * 2942fc3bdc3SEmanuele Giuseppe Esposito * Called with AioContext lock held, since many callback implementations 2952fc3bdc3SEmanuele Giuseppe Esposito * use bdrv_* functions that require to hold the lock. 2964ad35181SKevin Wolf */ 2974ad35181SKevin Wolf void (*abort)(Job *job); 2984ad35181SKevin Wolf 2994ad35181SKevin Wolf /** 3004ad35181SKevin Wolf * If the callback is not NULL, it will be invoked after a call to either 3014ad35181SKevin Wolf * .commit() or .abort(). Regardless of which callback is invoked after 3024ad35181SKevin Wolf * completion, .clean() will always be called, even if the job does not 3034ad35181SKevin Wolf * belong to a transaction group. 3042fc3bdc3SEmanuele Giuseppe Esposito * 3052fc3bdc3SEmanuele Giuseppe Esposito * Called with AioContext lock held, since many callbacs implementations 3062fc3bdc3SEmanuele Giuseppe Esposito * use bdrv_* functions that require to hold the lock. 3074ad35181SKevin Wolf */ 3084ad35181SKevin Wolf void (*clean)(Job *job); 3094ad35181SKevin Wolf 3109820933bSVladimir Sementsov-Ogievskiy /** 3119820933bSVladimir Sementsov-Ogievskiy * If the callback is not NULL, it will be invoked in job_cancel_async 31273895f38SHanna Reitz * 31373895f38SHanna Reitz * This function must return true if the job will be cancelled 31473895f38SHanna Reitz * immediately without any further I/O (mandatory if @force is 31573895f38SHanna Reitz * true), and false otherwise. This lets the generic job layer 31673895f38SHanna Reitz * know whether a job has been truly (force-)cancelled, or whether 31773895f38SHanna Reitz * it is just in a special completion mode (like mirror after 31873895f38SHanna Reitz * READY). 31973895f38SHanna Reitz * (If the callback is NULL, the job is assumed to terminate 32073895f38SHanna Reitz * without I/O.) 3212fc3bdc3SEmanuele Giuseppe Esposito * 3222fc3bdc3SEmanuele Giuseppe Esposito * Called with AioContext lock held, since many callback implementations 3232fc3bdc3SEmanuele Giuseppe Esposito * use bdrv_* functions that require to hold the lock. 3249820933bSVladimir Sementsov-Ogievskiy */ 32573895f38SHanna Reitz bool (*cancel)(Job *job, bool force); 3269820933bSVladimir Sementsov-Ogievskiy 3274ad35181SKevin Wolf 3282fc3bdc3SEmanuele Giuseppe Esposito /** 3292fc3bdc3SEmanuele Giuseppe Esposito * Called when the job is freed. 3302fc3bdc3SEmanuele Giuseppe Esposito * Called with AioContext lock held, since many callback implementations 3312fc3bdc3SEmanuele Giuseppe Esposito * use bdrv_* functions that require to hold the lock. 3322fc3bdc3SEmanuele Giuseppe Esposito */ 33380fa2c75SKevin Wolf void (*free)(Job *job); 33433e9e9bdSKevin Wolf }; 33533e9e9bdSKevin Wolf 336bb02b65cSKevin Wolf typedef enum JobCreateFlags { 337bb02b65cSKevin Wolf /* Default behavior */ 338bb02b65cSKevin Wolf JOB_DEFAULT = 0x00, 339bb02b65cSKevin Wolf /* Job is not QMP-created and should not send QMP events */ 340bb02b65cSKevin Wolf JOB_INTERNAL = 0x01, 341bb02b65cSKevin Wolf /* Job requires manual finalize step */ 342bb02b65cSKevin Wolf JOB_MANUAL_FINALIZE = 0x02, 343bb02b65cSKevin Wolf /* Job requires manual dismiss step */ 344bb02b65cSKevin Wolf JOB_MANUAL_DISMISS = 0x04, 345bb02b65cSKevin Wolf } JobCreateFlags; 346bb02b65cSKevin Wolf 34755c5a25aSEmanuele Giuseppe Esposito extern QemuMutex job_mutex; 34855c5a25aSEmanuele Giuseppe Esposito 3496f592e5aSEmanuele Giuseppe Esposito #define JOB_LOCK_GUARD() QEMU_LOCK_GUARD(&job_mutex) 35055c5a25aSEmanuele Giuseppe Esposito 3516f592e5aSEmanuele Giuseppe Esposito #define WITH_JOB_LOCK_GUARD() WITH_QEMU_LOCK_GUARD(&job_mutex) 35255c5a25aSEmanuele Giuseppe Esposito 35355c5a25aSEmanuele Giuseppe Esposito /** 35455c5a25aSEmanuele Giuseppe Esposito * job_lock: 35555c5a25aSEmanuele Giuseppe Esposito * 35655c5a25aSEmanuele Giuseppe Esposito * Take the mutex protecting the list of jobs and their status. 35755c5a25aSEmanuele Giuseppe Esposito * Most functions called by the monitor need to call job_lock 35855c5a25aSEmanuele Giuseppe Esposito * and job_unlock manually. On the other hand, function called 35955c5a25aSEmanuele Giuseppe Esposito * by the block jobs themselves and by the block layer will take the 36055c5a25aSEmanuele Giuseppe Esposito * lock for you. 36155c5a25aSEmanuele Giuseppe Esposito */ 36255c5a25aSEmanuele Giuseppe Esposito void job_lock(void); 36355c5a25aSEmanuele Giuseppe Esposito 36455c5a25aSEmanuele Giuseppe Esposito /** 36555c5a25aSEmanuele Giuseppe Esposito * job_unlock: 36655c5a25aSEmanuele Giuseppe Esposito * 36755c5a25aSEmanuele Giuseppe Esposito * Release the mutex protecting the list of jobs and their status. 36855c5a25aSEmanuele Giuseppe Esposito */ 36955c5a25aSEmanuele Giuseppe Esposito void job_unlock(void); 37055c5a25aSEmanuele Giuseppe Esposito 3717eaa8fb5SKevin Wolf /** 3727eaa8fb5SKevin Wolf * Allocate and return a new job transaction. Jobs can be added to the 3737eaa8fb5SKevin Wolf * transaction using job_txn_add_job(). 3747eaa8fb5SKevin Wolf * 3757eaa8fb5SKevin Wolf * The transaction is automatically freed when the last job completes or is 3767eaa8fb5SKevin Wolf * cancelled. 3777eaa8fb5SKevin Wolf * 3787eaa8fb5SKevin Wolf * All jobs in the transaction either complete successfully or fail/cancel as a 3797eaa8fb5SKevin Wolf * group. Jobs wait for each other before completing. Cancelling one job 3807eaa8fb5SKevin Wolf * cancels all jobs in the transaction. 3817eaa8fb5SKevin Wolf */ 3827eaa8fb5SKevin Wolf JobTxn *job_txn_new(void); 3837eaa8fb5SKevin Wolf 3847eaa8fb5SKevin Wolf /** 3857eaa8fb5SKevin Wolf * Release a reference that was previously acquired with job_txn_add_job or 3867eaa8fb5SKevin Wolf * job_txn_new. If it's the last reference to the object, it will be freed. 387*9bd4d3c2SEmanuele Giuseppe Esposito * 388*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock *not* held. 3897eaa8fb5SKevin Wolf */ 3907eaa8fb5SKevin Wolf void job_txn_unref(JobTxn *txn); 3917eaa8fb5SKevin Wolf 392afe1e8a7SEmanuele Giuseppe Esposito /* 393afe1e8a7SEmanuele Giuseppe Esposito * Same as job_txn_unref(), but called with job lock held. 394afe1e8a7SEmanuele Giuseppe Esposito * Might release the lock temporarily. 395afe1e8a7SEmanuele Giuseppe Esposito */ 396afe1e8a7SEmanuele Giuseppe Esposito void job_txn_unref_locked(JobTxn *txn); 397afe1e8a7SEmanuele Giuseppe Esposito 3987eaa8fb5SKevin Wolf /** 39933e9e9bdSKevin Wolf * Create a new long-running job and return it. 400afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 40133e9e9bdSKevin Wolf * 40233e9e9bdSKevin Wolf * @job_id: The id of the newly-created job, or %NULL for internal jobs 40333e9e9bdSKevin Wolf * @driver: The class object for the newly-created job. 4047eaa8fb5SKevin Wolf * @txn: The transaction this job belongs to, if any. %NULL otherwise. 40508be6fe2SKevin Wolf * @ctx: The AioContext to run the job coroutine in. 406bb02b65cSKevin Wolf * @flags: Creation flags for the job. See @JobCreateFlags. 4074ad35181SKevin Wolf * @cb: Completion function for the job. 4084ad35181SKevin Wolf * @opaque: Opaque pointer value passed to @cb. 40933e9e9bdSKevin Wolf * @errp: Error object. 41033e9e9bdSKevin Wolf */ 4117eaa8fb5SKevin Wolf void *job_create(const char *job_id, const JobDriver *driver, JobTxn *txn, 4127eaa8fb5SKevin Wolf AioContext *ctx, int flags, BlockCompletionFunc *cb, 4137eaa8fb5SKevin Wolf void *opaque, Error **errp); 41433e9e9bdSKevin Wolf 41580fa2c75SKevin Wolf /** 41680fa2c75SKevin Wolf * Add a reference to Job refcnt, it will be decreased with job_unref, and then 41780fa2c75SKevin Wolf * be freed if it comes to be the last reference. 418*9bd4d3c2SEmanuele Giuseppe Esposito * 419*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 42080fa2c75SKevin Wolf */ 421afe1e8a7SEmanuele Giuseppe Esposito void job_ref_locked(Job *job); 422afe1e8a7SEmanuele Giuseppe Esposito 42380fa2c75SKevin Wolf /** 424*9bd4d3c2SEmanuele Giuseppe Esposito * Release a reference that was previously acquired with job_ref_locked() or 42580fa2c75SKevin Wolf * job_create(). If it's the last reference to the object, it will be freed. 4266f592e5aSEmanuele Giuseppe Esposito * 4276f592e5aSEmanuele Giuseppe Esposito * Takes AioContext lock internally to invoke a job->driver callback. 428*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 42980fa2c75SKevin Wolf */ 430afe1e8a7SEmanuele Giuseppe Esposito void job_unref_locked(Job *job); 431afe1e8a7SEmanuele Giuseppe Esposito 43230a5c887SKevin Wolf /** 43330a5c887SKevin Wolf * @job: The job that has made progress 43430a5c887SKevin Wolf * @done: How much progress the job made since the last call 43530a5c887SKevin Wolf * 43630a5c887SKevin Wolf * Updates the progress counter of the job. 437afe1e8a7SEmanuele Giuseppe Esposito * 438afe1e8a7SEmanuele Giuseppe Esposito * May be called with mutex held or not held. 43930a5c887SKevin Wolf */ 44030a5c887SKevin Wolf void job_progress_update(Job *job, uint64_t done); 44130a5c887SKevin Wolf 44230a5c887SKevin Wolf /** 44330a5c887SKevin Wolf * @job: The job whose expected progress end value is set 44430a5c887SKevin Wolf * @remaining: Missing progress (on top of the current progress counter value) 44530a5c887SKevin Wolf * until the new expected end value is reached 44630a5c887SKevin Wolf * 44730a5c887SKevin Wolf * Sets the expected end value of the progress counter of a job so that a 44830a5c887SKevin Wolf * completion percentage can be calculated when the progress is updated. 449afe1e8a7SEmanuele Giuseppe Esposito * 450afe1e8a7SEmanuele Giuseppe Esposito * May be called with mutex held or not held. 45130a5c887SKevin Wolf */ 45230a5c887SKevin Wolf void job_progress_set_remaining(Job *job, uint64_t remaining); 45330a5c887SKevin Wolf 45462f13600SMax Reitz /** 45562f13600SMax Reitz * @job: The job whose expected progress end value is updated 45662f13600SMax Reitz * @delta: Value which is to be added to the current expected end 45762f13600SMax Reitz * value 45862f13600SMax Reitz * 45962f13600SMax Reitz * Increases the expected end value of the progress counter of a job. 46062f13600SMax Reitz * This is useful for parenthesis operations: If a job has to 46162f13600SMax Reitz * conditionally perform a high-priority operation as part of its 46262f13600SMax Reitz * progress, it calls this function with the expected operation's 46362f13600SMax Reitz * length before, and job_progress_update() afterwards. 46462f13600SMax Reitz * (So the operation acts as a parenthesis in regards to the main job 46562f13600SMax Reitz * operation running in background.) 466afe1e8a7SEmanuele Giuseppe Esposito * 467afe1e8a7SEmanuele Giuseppe Esposito * May be called with mutex held or not held. 46862f13600SMax Reitz */ 46962f13600SMax Reitz void job_progress_increase_remaining(Job *job, uint64_t delta); 47062f13600SMax Reitz 471da01ff7fSKevin Wolf /** 472da01ff7fSKevin Wolf * Conditionally enter the job coroutine if the job is ready to run, not 473da01ff7fSKevin Wolf * already busy and fn() returns true. fn() is called while under the job_lock 474da01ff7fSKevin Wolf * critical section. 475*9bd4d3c2SEmanuele Giuseppe Esposito * 476*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held, but might release it temporarily. 477afe1e8a7SEmanuele Giuseppe Esposito */ 478afe1e8a7SEmanuele Giuseppe Esposito void job_enter_cond_locked(Job *job, bool(*fn)(Job *job)); 479afe1e8a7SEmanuele Giuseppe Esposito 480da01ff7fSKevin Wolf /** 481da01ff7fSKevin Wolf * @job: A job that has not yet been started. 482da01ff7fSKevin Wolf * 483da01ff7fSKevin Wolf * Begins execution of a job. 484da01ff7fSKevin Wolf * Takes ownership of one reference to the job object. 485afe1e8a7SEmanuele Giuseppe Esposito * 486afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 487da01ff7fSKevin Wolf */ 488da01ff7fSKevin Wolf void job_start(Job *job); 489da01ff7fSKevin Wolf 490da01ff7fSKevin Wolf /** 4915d43e86eSKevin Wolf * @job: The job to enter. 4925d43e86eSKevin Wolf * 4935d43e86eSKevin Wolf * Continue the specified job by entering the coroutine. 494afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 4955d43e86eSKevin Wolf */ 4965d43e86eSKevin Wolf void job_enter(Job *job); 4975d43e86eSKevin Wolf 4985d43e86eSKevin Wolf /** 499da01ff7fSKevin Wolf * @job: The job that is ready to pause. 500da01ff7fSKevin Wolf * 501da01ff7fSKevin Wolf * Pause now if job_pause() has been called. Jobs that perform lots of I/O 502da01ff7fSKevin Wolf * must call this between requests so that the job can be paused. 503afe1e8a7SEmanuele Giuseppe Esposito * 504afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 505da01ff7fSKevin Wolf */ 506da01ff7fSKevin Wolf void coroutine_fn job_pause_point(Job *job); 507da01ff7fSKevin Wolf 5085d43e86eSKevin Wolf /** 5095d43e86eSKevin Wolf * @job: The job that calls the function. 510198c49ccSKevin Wolf * 511198c49ccSKevin Wolf * Yield the job coroutine. 512afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 513198c49ccSKevin Wolf */ 51406753a07SPaolo Bonzini void coroutine_fn job_yield(Job *job); 515198c49ccSKevin Wolf 516198c49ccSKevin Wolf /** 517198c49ccSKevin Wolf * @job: The job that calls the function. 5185d43e86eSKevin Wolf * @ns: How many nanoseconds to stop for. 5195d43e86eSKevin Wolf * 5205d43e86eSKevin Wolf * Put the job to sleep (assuming that it wasn't canceled) for @ns 5215d43e86eSKevin Wolf * %QEMU_CLOCK_REALTIME nanoseconds. Canceling the job will immediately 5225d43e86eSKevin Wolf * interrupt the wait. 523afe1e8a7SEmanuele Giuseppe Esposito * 524afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 5255d43e86eSKevin Wolf */ 5265d43e86eSKevin Wolf void coroutine_fn job_sleep_ns(Job *job, int64_t ns); 5275d43e86eSKevin Wolf 528252291eaSKevin Wolf /** Returns the JobType of a given Job. */ 529252291eaSKevin Wolf JobType job_type(const Job *job); 530252291eaSKevin Wolf 531252291eaSKevin Wolf /** Returns the enum string for the JobType of a given Job. */ 532252291eaSKevin Wolf const char *job_type_str(const Job *job); 533252291eaSKevin Wolf 534456273b0SKevin Wolf /** Returns true if the job should not be visible to the management layer. */ 535456273b0SKevin Wolf bool job_is_internal(Job *job); 536456273b0SKevin Wolf 537afe1e8a7SEmanuele Giuseppe Esposito /** 538afe1e8a7SEmanuele Giuseppe Esposito * Returns whether the job is being cancelled. 539afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 540afe1e8a7SEmanuele Giuseppe Esposito */ 541daa7f2f9SKevin Wolf bool job_is_cancelled(Job *job); 542daa7f2f9SKevin Wolf 543afe1e8a7SEmanuele Giuseppe Esposito /* Same as job_is_cancelled(), but called with job lock held. */ 544afe1e8a7SEmanuele Giuseppe Esposito bool job_is_cancelled_locked(Job *job); 545afe1e8a7SEmanuele Giuseppe Esposito 54608b83bffSHanna Reitz /** 54708b83bffSHanna Reitz * Returns whether the job is scheduled for cancellation (at an 54808b83bffSHanna Reitz * indefinite point). 549afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 55008b83bffSHanna Reitz */ 55108b83bffSHanna Reitz bool job_cancel_requested(Job *job); 55208b83bffSHanna Reitz 553afe1e8a7SEmanuele Giuseppe Esposito /** 554afe1e8a7SEmanuele Giuseppe Esposito * Returns whether the job is in a completed state. 555*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 556afe1e8a7SEmanuele Giuseppe Esposito */ 557afe1e8a7SEmanuele Giuseppe Esposito bool job_is_completed_locked(Job *job); 558afe1e8a7SEmanuele Giuseppe Esposito 559afe1e8a7SEmanuele Giuseppe Esposito /** 560afe1e8a7SEmanuele Giuseppe Esposito * Returns whether the job is ready to be completed. 561afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 562afe1e8a7SEmanuele Giuseppe Esposito */ 563df956ae2SKevin Wolf bool job_is_ready(Job *job); 564df956ae2SKevin Wolf 565afe1e8a7SEmanuele Giuseppe Esposito /* Same as job_is_ready(), but called with job lock held. */ 566afe1e8a7SEmanuele Giuseppe Esposito bool job_is_ready_locked(Job *job); 567afe1e8a7SEmanuele Giuseppe Esposito 568e7c1d78bSKevin Wolf /** 569b15de828SKevin Wolf * Request @job to pause at the next pause point. Must be paired with 570b15de828SKevin Wolf * job_resume(). If the job is supposed to be resumed by user action, call 571*9bd4d3c2SEmanuele Giuseppe Esposito * job_user_pause_locked() instead. 572*9bd4d3c2SEmanuele Giuseppe Esposito * 573*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock *not* held. 574b15de828SKevin Wolf */ 575b15de828SKevin Wolf void job_pause(Job *job); 576b15de828SKevin Wolf 577afe1e8a7SEmanuele Giuseppe Esposito /* Same as job_pause(), but called with job lock held. */ 578afe1e8a7SEmanuele Giuseppe Esposito void job_pause_locked(Job *job); 579afe1e8a7SEmanuele Giuseppe Esposito 580*9bd4d3c2SEmanuele Giuseppe Esposito /** Resumes a @job paused with job_pause. Called with job lock *not* held. */ 581b15de828SKevin Wolf void job_resume(Job *job); 582b15de828SKevin Wolf 583afe1e8a7SEmanuele Giuseppe Esposito /* 584afe1e8a7SEmanuele Giuseppe Esposito * Same as job_resume(), but called with job lock held. 585afe1e8a7SEmanuele Giuseppe Esposito * Might release the lock temporarily. 586afe1e8a7SEmanuele Giuseppe Esposito */ 587afe1e8a7SEmanuele Giuseppe Esposito void job_resume_locked(Job *job); 588afe1e8a7SEmanuele Giuseppe Esposito 589b15de828SKevin Wolf /** 590b15de828SKevin Wolf * Asynchronously pause the specified @job. 591b15de828SKevin Wolf * Do not allow a resume until a matching call to job_user_resume. 592*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 593b15de828SKevin Wolf */ 594afe1e8a7SEmanuele Giuseppe Esposito void job_user_pause_locked(Job *job, Error **errp); 595afe1e8a7SEmanuele Giuseppe Esposito 596*9bd4d3c2SEmanuele Giuseppe Esposito /** 597*9bd4d3c2SEmanuele Giuseppe Esposito * Returns true if the job is user-paused. 598*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 599*9bd4d3c2SEmanuele Giuseppe Esposito */ 600afe1e8a7SEmanuele Giuseppe Esposito bool job_user_paused_locked(Job *job); 601afe1e8a7SEmanuele Giuseppe Esposito 602b15de828SKevin Wolf /** 603b15de828SKevin Wolf * Resume the specified @job. 604*9bd4d3c2SEmanuele Giuseppe Esposito * Must be paired with a preceding job_user_pause_locked. 605*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held, but might release it temporarily. 606afe1e8a7SEmanuele Giuseppe Esposito */ 607afe1e8a7SEmanuele Giuseppe Esposito void job_user_resume_locked(Job *job, Error **errp); 608afe1e8a7SEmanuele Giuseppe Esposito 609b15de828SKevin Wolf /** 610e7c1d78bSKevin Wolf * Get the next element from the list of block jobs after @job, or the 611e7c1d78bSKevin Wolf * first one if @job is %NULL. 612e7c1d78bSKevin Wolf * 613e7c1d78bSKevin Wolf * Returns the requested job, or %NULL if there are no more jobs left. 614*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock *not* held. 615e7c1d78bSKevin Wolf */ 616e7c1d78bSKevin Wolf Job *job_next(Job *job); 617e7c1d78bSKevin Wolf 618afe1e8a7SEmanuele Giuseppe Esposito /* Same as job_next(), but called with job lock held. */ 619afe1e8a7SEmanuele Giuseppe Esposito Job *job_next_locked(Job *job); 620afe1e8a7SEmanuele Giuseppe Esposito 621e7c1d78bSKevin Wolf /** 622e7c1d78bSKevin Wolf * Get the job identified by @id (which must not be %NULL). 623e7c1d78bSKevin Wolf * 624e7c1d78bSKevin Wolf * Returns the requested job, or %NULL if it doesn't exist. 625*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 626e7c1d78bSKevin Wolf */ 627afe1e8a7SEmanuele Giuseppe Esposito Job *job_get_locked(const char *id); 628afe1e8a7SEmanuele Giuseppe Esposito 629a50c2ab8SKevin Wolf /** 630a50c2ab8SKevin Wolf * Check whether the verb @verb can be applied to @job in its current state. 631a50c2ab8SKevin Wolf * Returns 0 if the verb can be applied; otherwise errp is set and -EPERM 632a50c2ab8SKevin Wolf * returned. 633*9bd4d3c2SEmanuele Giuseppe Esposito * 634*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 635a50c2ab8SKevin Wolf */ 636afe1e8a7SEmanuele Giuseppe Esposito int job_apply_verb_locked(Job *job, JobVerb verb, Error **errp); 637afe1e8a7SEmanuele Giuseppe Esposito 638afe1e8a7SEmanuele Giuseppe Esposito /** 639afe1e8a7SEmanuele Giuseppe Esposito * The @job could not be started, free it. 640afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 641afe1e8a7SEmanuele Giuseppe Esposito */ 6424ad35181SKevin Wolf void job_early_fail(Job *job); 6434ad35181SKevin Wolf 644afe1e8a7SEmanuele Giuseppe Esposito /** 645afe1e8a7SEmanuele Giuseppe Esposito * Moves the @job from RUNNING to READY. 646afe1e8a7SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 647afe1e8a7SEmanuele Giuseppe Esposito */ 6482e1795b5SKevin Wolf void job_transition_to_ready(Job *job); 6492e1795b5SKevin Wolf 650*9bd4d3c2SEmanuele Giuseppe Esposito /** 651*9bd4d3c2SEmanuele Giuseppe Esposito * Asynchronously complete the specified @job. 652*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held, but might release it temporarily. 653afe1e8a7SEmanuele Giuseppe Esposito */ 654afe1e8a7SEmanuele Giuseppe Esposito void job_complete_locked(Job *job, Error **errp); 655afe1e8a7SEmanuele Giuseppe Esposito 6563d70ff53SKevin Wolf /** 6573d70ff53SKevin Wolf * Asynchronously cancel the specified @job. If @force is true, the job should 6583d70ff53SKevin Wolf * be cancelled immediately without waiting for a consistent state. 659*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 6603d70ff53SKevin Wolf */ 661afe1e8a7SEmanuele Giuseppe Esposito void job_cancel_locked(Job *job, bool force); 662afe1e8a7SEmanuele Giuseppe Esposito 6633d70ff53SKevin Wolf /** 664*9bd4d3c2SEmanuele Giuseppe Esposito * Cancels the specified job like job_cancel_locked(), but may refuse 665*9bd4d3c2SEmanuele Giuseppe Esposito * to do so if the operation isn't meaningful in the current state of the job. 666*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 6673d70ff53SKevin Wolf */ 668afe1e8a7SEmanuele Giuseppe Esposito void job_user_cancel_locked(Job *job, bool force, Error **errp); 669afe1e8a7SEmanuele Giuseppe Esposito 6703d70ff53SKevin Wolf /** 6713d70ff53SKevin Wolf * Synchronously cancel the @job. The completion callback is called 6724cfb3f05SHanna Reitz * before the function returns. If @force is false, the job may 6734cfb3f05SHanna Reitz * actually complete instead of canceling itself; the circumstances 6744cfb3f05SHanna Reitz * under which this happens depend on the kind of job that is active. 6753d70ff53SKevin Wolf * 6763d70ff53SKevin Wolf * Returns the return value from the job if the job actually completed 6773d70ff53SKevin Wolf * during the call, or -ECANCELED if it was canceled. 67830c070a5SKevin Wolf * 6796f592e5aSEmanuele Giuseppe Esposito * Called with job_lock *not* held. 6803d70ff53SKevin Wolf */ 6814cfb3f05SHanna Reitz int job_cancel_sync(Job *job, bool force); 6823d70ff53SKevin Wolf 683afe1e8a7SEmanuele Giuseppe Esposito /* Same as job_cancel_sync, but called with job lock held. */ 684afe1e8a7SEmanuele Giuseppe Esposito int job_cancel_sync_locked(Job *job, bool force); 685afe1e8a7SEmanuele Giuseppe Esposito 686afe1e8a7SEmanuele Giuseppe Esposito /** 687afe1e8a7SEmanuele Giuseppe Esposito * Synchronously force-cancels all jobs using job_cancel_sync_locked(). 688afe1e8a7SEmanuele Giuseppe Esposito * 689afe1e8a7SEmanuele Giuseppe Esposito * Called with job_lock *not* held. 690afe1e8a7SEmanuele Giuseppe Esposito */ 6913d70ff53SKevin Wolf void job_cancel_sync_all(void); 6923d70ff53SKevin Wolf 6933d70ff53SKevin Wolf /** 6943d70ff53SKevin Wolf * @job: The job to be completed. 695*9bd4d3c2SEmanuele Giuseppe Esposito * @errp: Error object which may be set by job_complete_locked(); this is not 6963d70ff53SKevin Wolf * necessarily set on every error, the job return value has to be 6973d70ff53SKevin Wolf * checked as well. 6983d70ff53SKevin Wolf * 6993d70ff53SKevin Wolf * Synchronously complete the job. The completion callback is called before the 7003d70ff53SKevin Wolf * function returns, unless it is NULL (which is permissible when using this 7013d70ff53SKevin Wolf * function). 7023d70ff53SKevin Wolf * 7033d70ff53SKevin Wolf * Returns the return value from the job. 704*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job_lock held. 7053d70ff53SKevin Wolf */ 706afe1e8a7SEmanuele Giuseppe Esposito int job_complete_sync_locked(Job *job, Error **errp); 707afe1e8a7SEmanuele Giuseppe Esposito 7087eaa8fb5SKevin Wolf /** 7097eaa8fb5SKevin Wolf * For a @job that has finished its work and is pending awaiting explicit 7107eaa8fb5SKevin Wolf * acknowledgement to commit its work, this will commit that work. 7117eaa8fb5SKevin Wolf * 7127eaa8fb5SKevin Wolf * FIXME: Make the below statement universally true: 7137eaa8fb5SKevin Wolf * For jobs that support the manual workflow mode, all graph changes that occur 7147eaa8fb5SKevin Wolf * as a result will occur after this command and before a successful reply. 715*9bd4d3c2SEmanuele Giuseppe Esposito * 716*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 7177eaa8fb5SKevin Wolf */ 718afe1e8a7SEmanuele Giuseppe Esposito void job_finalize_locked(Job *job, Error **errp); 719afe1e8a7SEmanuele Giuseppe Esposito 7205f9a6a08SKevin Wolf /** 7215f9a6a08SKevin Wolf * Remove the concluded @job from the query list and resets the passed pointer 7225f9a6a08SKevin Wolf * to %NULL. Returns an error if the job is not actually concluded. 723*9bd4d3c2SEmanuele Giuseppe Esposito * 724*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job lock held. 7255f9a6a08SKevin Wolf */ 726afe1e8a7SEmanuele Giuseppe Esposito void job_dismiss_locked(Job **job, Error **errp); 727afe1e8a7SEmanuele Giuseppe Esposito 7286a74c075SKevin Wolf /** 7296a74c075SKevin Wolf * Synchronously finishes the given @job. If @finish is given, it is called to 7306a74c075SKevin Wolf * trigger completion or cancellation of the job. 7316a74c075SKevin Wolf * 7326a74c075SKevin Wolf * Returns 0 if the job is successfully completed, -ECANCELED if the job was 7336a74c075SKevin Wolf * cancelled before completing, and -errno in other error cases. 73430c070a5SKevin Wolf * 735*9bd4d3c2SEmanuele Giuseppe Esposito * Called with job_lock held, but might release it temporarily. 736afe1e8a7SEmanuele Giuseppe Esposito */ 737afe1e8a7SEmanuele Giuseppe Esposito int job_finish_sync_locked(Job *job, void (*finish)(Job *, Error **errp), 738afe1e8a7SEmanuele Giuseppe Esposito Error **errp); 7396a74c075SKevin Wolf 7403ed4f708SEmanuele Giuseppe Esposito /** 7413ed4f708SEmanuele Giuseppe Esposito * Sets the @job->aio_context. 7423ed4f708SEmanuele Giuseppe Esposito * Called with job_mutex *not* held. 7433ed4f708SEmanuele Giuseppe Esposito * 7443ed4f708SEmanuele Giuseppe Esposito * This function must run in the main thread to protect against 7453ed4f708SEmanuele Giuseppe Esposito * concurrent read in job_finish_sync_locked(), takes the job_mutex 7463ed4f708SEmanuele Giuseppe Esposito * lock to protect against the read in job_do_yield_locked(), and must 7473ed4f708SEmanuele Giuseppe Esposito * be called when the job is quiescent. 7483ed4f708SEmanuele Giuseppe Esposito */ 7493ed4f708SEmanuele Giuseppe Esposito void job_set_aio_context(Job *job, AioContext *ctx); 7503ed4f708SEmanuele Giuseppe Esposito 75133e9e9bdSKevin Wolf #endif 752