2 * Declarations for background jobs
4 * Copyright (c) 2011 IBM Corp.
5 * Copyright (c) 2012, 2018 Red Hat, Inc.
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
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"
35 typedef struct JobDriver JobDriver
;
36 typedef struct JobTxn JobTxn
;
40 * Long-running operation.
43 /** The ID of the job. May be NULL for internal jobs. */
46 /** The type of this job. */
47 const JobDriver
*driver
;
49 /** Reference count of the block job */
52 /** Current state; See @JobStatus for details. */
55 /** AioContext to run the job coroutine in */
56 AioContext
*aio_context
;
59 * The coroutine that executes the job. If not NULL, it is reentered when
60 * busy is false and the job is cancelled.
65 * Timer that is used by @job_sleep_ns. Accessed under job_mutex (in
68 QEMUTimer sleep_timer
;
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.
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).
81 * When the job is deferred to the main loop, busy is true as long as the
82 * bottom half is still pending.
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.
93 * Set to true if the job is paused by user. Can be unpaused with the
94 * block-job-resume QMP command.
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.
107 * Set to true if the job should abort immediately without waiting
108 * for data to be in sync.
112 /** Set to true when the job has deferred work to the main loop. */
113 bool deferred_to_main_loop
;
115 /** True if this job should automatically finalize itself */
118 /** True if this job should automatically dismiss itself */
121 ProgressMeter progress
;
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.
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.
137 /** The completion function that will be called when the job completes. */
138 BlockCompletionFunc
*cb
;
140 /** The opaque value that is passed to the completion function. */
143 /** Notifiers called when a cancelled job is finalised */
144 NotifierList on_finalize_cancelled
;
146 /** Notifiers called when a successfully completed job is finalised */
147 NotifierList on_finalize_completed
;
149 /** Notifiers called when the job transitions to PENDING */
150 NotifierList on_pending
;
152 /** Notifiers called when the job transitions to READY */
153 NotifierList on_ready
;
155 /** Notifiers called when the job coroutine yields or terminates */
156 NotifierList on_idle
;
158 /** Element of the list of jobs */
159 QLIST_ENTRY(Job
) job_list
;
161 /** Transaction this job is part of */
164 /** Element of the list of jobs in a job transaction */
165 QLIST_ENTRY(Job
) txn_list
;
169 * Callbacks and other information about a Job driver.
174 * These fields are initialized when this object is created,
175 * and are never changed afterwards
178 /** Derived Job struct size */
179 size_t instance_size
;
181 /** Enum describing the operation */
185 * Mandatory: Entrypoint for the Coroutine.
187 * This callback will be invoked when moving from CREATED to RUNNING.
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.
194 * This callback must be run in the job's context.
196 int coroutine_fn (*run
)(Job
*job
, Error
**errp
);
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
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.
210 void coroutine_fn (*pause
)(Job
*job
);
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.
217 void coroutine_fn (*resume
)(Job
*job
);
220 * Global state (GS) API. These functions run under the BQL.
222 * See include/block/block-global-state.h for more information about
227 * Called when the job is resumed by the user (i.e. user_paused becomes
228 * false). .user_resume is called before .resume.
230 void (*user_resume
)(Job
*job
);
233 * Optional callback for job types whose completion must be triggered
236 void (*complete
)(Job
*job
, Error
**errp
);
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.
243 * This callback will not be invoked if the job has already failed.
244 * If it fails, abort and then clean will be called.
246 int (*prepare
)(Job
*job
);
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.
253 * All jobs will complete with a call to either .commit() or .abort() but
256 void (*commit
)(Job
*job
);
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.
263 * All jobs will complete with a call to either .commit() or .abort() but
266 void (*abort
)(Job
*job
);
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.
274 void (*clean
)(Job
*job
);
277 * If the callback is not NULL, it will be invoked in job_cancel_async
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
285 * (If the callback is NULL, the job is assumed to terminate
288 bool (*cancel
)(Job
*job
, bool force
);
291 /** Called when the job is freed */
292 void (*free
)(Job
*job
);
295 typedef enum JobCreateFlags
{
296 /* Default behavior */
298 /* Job is not QMP-created and should not send QMP events */
300 /* Job requires manual finalize step */
301 JOB_MANUAL_FINALIZE
= 0x02,
302 /* Job requires manual dismiss step */
303 JOB_MANUAL_DISMISS
= 0x04,
307 * Allocate and return a new job transaction. Jobs can be added to the
308 * transaction using job_txn_add_job().
310 * The transaction is automatically freed when the last job completes or is
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.
317 JobTxn
*job_txn_new(void);
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.
323 void job_txn_unref(JobTxn
*txn
);
326 * @txn: The transaction (may be NULL)
327 * @job: Job to add to the transaction
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.
333 * If @txn is NULL, the function does nothing.
335 void job_txn_add_job(JobTxn
*txn
, Job
*job
);
338 * Create a new long-running job and return it.
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.
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
);
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.
357 void job_ref(Job
*job
);
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.
363 void job_unref(Job
*job
);
366 * @job: The job that has made progress
367 * @done: How much progress the job made since the last call
369 * Updates the progress counter of the job.
371 void job_progress_update(Job
*job
, uint64_t done
);
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
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.
381 void job_progress_set_remaining(Job
*job
, uint64_t remaining
);
384 * @job: The job whose expected progress end value is updated
385 * @delta: Value which is to be added to the current expected end
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.)
396 void job_progress_increase_remaining(Job
*job
, uint64_t delta
);
398 /** To be called when a cancelled job is finalised. */
399 void job_event_cancelled(Job
*job
);
401 /** To be called when a successfully completed job is finalised. */
402 void job_event_completed(Job
*job
);
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
409 void job_enter_cond(Job
*job
, bool(*fn
)(Job
*job
));
412 * @job: A job that has not yet been started.
414 * Begins execution of a job.
415 * Takes ownership of one reference to the job object.
417 void job_start(Job
*job
);
420 * @job: The job to enter.
422 * Continue the specified job by entering the coroutine.
424 void job_enter(Job
*job
);
427 * @job: The job that is ready to pause.
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.
432 void coroutine_fn
job_pause_point(Job
*job
);
435 * @job: The job that calls the function.
437 * Yield the job coroutine.
439 void job_yield(Job
*job
);
442 * @job: The job that calls the function.
443 * @ns: How many nanoseconds to stop for.
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.
449 void coroutine_fn
job_sleep_ns(Job
*job
, int64_t ns
);
452 /** Returns the JobType of a given Job. */
453 JobType
job_type(const Job
*job
);
455 /** Returns the enum string for the JobType of a given Job. */
456 const char *job_type_str(const Job
*job
);
458 /** Returns true if the job should not be visible to the management layer. */
459 bool job_is_internal(Job
*job
);
461 /** Returns whether the job is being cancelled. */
462 bool job_is_cancelled(Job
*job
);
465 * Returns whether the job is scheduled for cancellation (at an
468 bool job_cancel_requested(Job
*job
);
470 /** Returns whether the job is in a completed state. */
471 bool job_is_completed(Job
*job
);
473 /** Returns whether the job is ready to be completed. */
474 bool job_is_ready(Job
*job
);
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.
481 void job_pause(Job
*job
);
483 /** Resumes a @job paused with job_pause. */
484 void job_resume(Job
*job
);
487 * Asynchronously pause the specified @job.
488 * Do not allow a resume until a matching call to job_user_resume.
490 void job_user_pause(Job
*job
, Error
**errp
);
492 /** Returns true if the job is user-paused. */
493 bool job_user_paused(Job
*job
);
496 * Resume the specified @job.
497 * Must be paired with a preceding job_user_pause.
499 void job_user_resume(Job
*job
, Error
**errp
);
502 * Get the next element from the list of block jobs after @job, or the
503 * first one if @job is %NULL.
505 * Returns the requested job, or %NULL if there are no more jobs left.
507 Job
*job_next(Job
*job
);
510 * Get the job identified by @id (which must not be %NULL).
512 * Returns the requested job, or %NULL if it doesn't exist.
514 Job
*job_get(const char *id
);
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
521 int job_apply_verb(Job
*job
, JobVerb verb
, Error
**errp
);
523 /** The @job could not be started, free it. */
524 void job_early_fail(Job
*job
);
526 /** Moves the @job from RUNNING to READY */
527 void job_transition_to_ready(Job
*job
);
529 /** Asynchronously complete the specified @job. */
530 void job_complete(Job
*job
, Error
**errp
);
533 * Asynchronously cancel the specified @job. If @force is true, the job should
534 * be cancelled immediately without waiting for a consistent state.
536 void job_cancel(Job
*job
, bool force
);
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.
542 void job_user_cancel(Job
*job
, bool force
, Error
**errp
);
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.
550 * Returns the return value from the job if the job actually completed
551 * during the call, or -ECANCELED if it was canceled.
553 * Callers must hold the AioContext lock of job->aio_context.
555 int job_cancel_sync(Job
*job
, bool force
);
557 /** Synchronously force-cancels all jobs using job_cancel_sync(). */
558 void job_cancel_sync_all(void);
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
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
570 * Returns the return value from the job.
572 * Callers must hold the AioContext lock of job->aio_context.
574 int job_complete_sync(Job
*job
, Error
**errp
);
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.
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.
584 void job_finalize(Job
*job
, Error
**errp
);
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.
590 void job_dismiss(Job
**job
, Error
**errp
);
593 * Synchronously finishes the given @job. If @finish is given, it is called to
594 * trigger completion or cancellation of the job.
596 * Returns 0 if the job is successfully completed, -ECANCELED if the job was
597 * cancelled before completing, and -errno in other error cases.
599 * Callers must hold the AioContext lock of job->aio_context.
601 int job_finish_sync(Job
*job
, void (*finish
)(Job
*, Error
**errp
), Error
**errp
);