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
34typedef struct JobDriver JobDriver;
35typedef struct JobTxn JobTxn;
36
37
38/**
39 * Long-running operation.
40 */
41typedef struct Job {
42 /** The ID of the job. May be NULL for internal jobs. */
43 char *id;
44
45 /** The type of this job. */
46 const JobDriver *driver;
47
48 /** Reference count of the block job */
49 int refcnt;
50
51 /** Current state; See @JobStatus for details. */
52 JobStatus status;
53
54 /** AioContext to run the job coroutine in */
55 AioContext *aio_context;
56
57 /**
58 * The coroutine that executes the job. If not NULL, it is reentered when
59 * busy is false and the job is cancelled.
60 */
61 Coroutine *co;
62
63 /**
64 * Timer that is used by @job_sleep_ns. Accessed under job_mutex (in
65 * job.c).
66 */
67 QEMUTimer sleep_timer;
68
69 /**
70 * Counter for pause request. If non-zero, the block job is either paused,
71 * or if busy == true will pause itself as soon as possible.
72 */
73 int pause_count;
74
75 /**
76 * Set to false by the job while the coroutine has yielded and may be
77 * re-entered by job_enter(). There may still be I/O or event loop activity
78 * pending. Accessed under block_job_mutex (in blockjob.c).
79 *
80 * 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 */
178struct 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
273typedef 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 */
295JobTxn *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 */
301void 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 */
313void 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 */
327void *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 */
335void 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 */
341void 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 */
349void 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 */
359void 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 */
374void job_progress_increase_remaining(Job *job, uint64_t delta);
375
376/** To be called when a cancelled job is finalised. */
377void job_event_cancelled(Job *job);
378
379/** To be called when a successfully completed job is finalised. */
380void 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 */
387void 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 */
395void job_start(Job *job);
396
397/**
398 * @job: The job to enter.
399 *
400 * Continue the specified job by entering the coroutine.
401 */
402void 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 */
410void coroutine_fn job_pause_point(Job *job);
411
412/**
413 * @job: The job that calls the function.
414 *
415 * Yield the job coroutine.
416 */
417void 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 */
427void coroutine_fn job_sleep_ns(Job *job, int64_t ns);
428
429
430/** Returns the JobType of a given Job. */
431JobType job_type(const Job *job);
432
433/** Returns the enum string for the JobType of a given Job. */
434const char *job_type_str(const Job *job);
435
436/** Returns true if the job should not be visible to the management layer. */
437bool job_is_internal(Job *job);
438
439/** Returns whether the job is scheduled for cancellation. */
440bool job_is_cancelled(Job *job);
441
442/** Returns whether the job is in a completed state. */
443bool job_is_completed(Job *job);
444
445/** Returns whether the job is ready to be completed. */
446bool 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 */
453void job_pause(Job *job);
454
455/** Resumes a @job paused with job_pause. */
456void 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 */
462void job_user_pause(Job *job, Error **errp);
463
464/** Returns true if the job is user-paused. */
465bool job_user_paused(Job *job);
466
467/**
468 * Resume the specified @job.
469 * Must be paired with a preceding job_user_pause.
470 */
471void 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 */
477void 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 */
485Job *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 */
492Job *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 */
499int job_apply_verb(Job *job, JobVerb verb, Error **errp);
500
501/** The @job could not be started, free it. */
502void job_early_fail(Job *job);
503
504/** Moves the @job from RUNNING to READY */
505void job_transition_to_ready(Job *job);
506
507/** Asynchronously complete the specified @job. */
508void 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 */
514void 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 */
520void 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 */
533int job_cancel_sync(Job *job);
534
535/** Synchronously cancels all jobs using job_cancel_sync(). */
536void 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 */
552int 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 */
562void 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 */
568void 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 */
579int job_finish_sync(Job *job, void (*finish)(Job *, Error **errp), Error **errp);
580
581#endif
582