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