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