This doesn't actually move any transaction code to Job yet, but it renames the type for transactions from BlockJobTxn to JobTxn and makes them contain Jobs rather than BlockJobs Signed-off-by: Kevin Wolf <kwolf@redhat.com> Reviewed-by: Max Reitz <mreitz@redhat.com>
417 lines
12 KiB
C
417 lines
12 KiB
C
/*
|
|
* Declarations for background jobs
|
|
*
|
|
* Copyright (c) 2011 IBM Corp.
|
|
* Copyright (c) 2012, 2018 Red Hat, Inc.
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
* of this software and associated documentation files (the "Software"), to deal
|
|
* in the Software without restriction, including without limitation the rights
|
|
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
* copies of the Software, and to permit persons to whom the Software is
|
|
* furnished to do so, subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be included in
|
|
* all copies or substantial portions of the Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
|
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
* THE SOFTWARE.
|
|
*/
|
|
|
|
#ifndef JOB_H
|
|
#define JOB_H
|
|
|
|
#include "qapi/qapi-types-block-core.h"
|
|
#include "qemu/queue.h"
|
|
#include "qemu/coroutine.h"
|
|
#include "block/aio.h"
|
|
|
|
typedef struct JobDriver JobDriver;
|
|
|
|
/**
|
|
* Long-running operation.
|
|
*/
|
|
typedef struct Job {
|
|
/** The ID of the job. May be NULL for internal jobs. */
|
|
char *id;
|
|
|
|
/** The type of this job. */
|
|
const JobDriver *driver;
|
|
|
|
/** Reference count of the block job */
|
|
int refcnt;
|
|
|
|
/** Current state; See @JobStatus for details. */
|
|
JobStatus status;
|
|
|
|
/** AioContext to run the job coroutine in */
|
|
AioContext *aio_context;
|
|
|
|
/**
|
|
* The coroutine that executes the job. If not NULL, it is reentered when
|
|
* busy is false and the job is cancelled.
|
|
*/
|
|
Coroutine *co;
|
|
|
|
/**
|
|
* Timer that is used by @job_sleep_ns. Accessed under job_mutex (in
|
|
* job.c).
|
|
*/
|
|
QEMUTimer sleep_timer;
|
|
|
|
/**
|
|
* Counter for pause request. If non-zero, the block job is either paused,
|
|
* or if busy == true will pause itself as soon as possible.
|
|
*/
|
|
int pause_count;
|
|
|
|
/**
|
|
* Set to false by the job while the coroutine has yielded and may be
|
|
* re-entered by block_job_enter(). There may still be I/O or event loop
|
|
* activity pending. Accessed under block_job_mutex (in blockjob.c).
|
|
*/
|
|
bool busy;
|
|
|
|
/**
|
|
* Set to true by the job while it is in a quiescent state, where
|
|
* no I/O or event loop activity is pending.
|
|
*/
|
|
bool paused;
|
|
|
|
/**
|
|
* Set to true if the job is paused by user. Can be unpaused with the
|
|
* block-job-resume QMP command.
|
|
*/
|
|
bool user_paused;
|
|
|
|
/**
|
|
* Set to true if the job should cancel itself. The flag must
|
|
* always be tested just before toggling the busy flag from false
|
|
* to true. After a job has been cancelled, it should only yield
|
|
* if #aio_poll will ("sooner or later") reenter the coroutine.
|
|
*/
|
|
bool cancelled;
|
|
|
|
/**
|
|
* Set to true if the job should abort immediately without waiting
|
|
* for data to be in sync.
|
|
*/
|
|
bool force_cancel;
|
|
|
|
/** Set to true when the job has deferred work to the main loop. */
|
|
bool deferred_to_main_loop;
|
|
|
|
/** True if this job should automatically finalize itself */
|
|
bool auto_finalize;
|
|
|
|
/** True if this job should automatically dismiss itself */
|
|
bool auto_dismiss;
|
|
|
|
/** ret code passed to block_job_completed. */
|
|
int ret;
|
|
|
|
/** The completion function that will be called when the job completes. */
|
|
BlockCompletionFunc *cb;
|
|
|
|
/** The opaque value that is passed to the completion function. */
|
|
void *opaque;
|
|
|
|
/** Notifiers called when a cancelled job is finalised */
|
|
NotifierList on_finalize_cancelled;
|
|
|
|
/** Notifiers called when a successfully completed job is finalised */
|
|
NotifierList on_finalize_completed;
|
|
|
|
/** Notifiers called when the job transitions to PENDING */
|
|
NotifierList on_pending;
|
|
|
|
/** Element of the list of jobs */
|
|
QLIST_ENTRY(Job) job_list;
|
|
|
|
/** Element of the list of jobs in a job transaction */
|
|
QLIST_ENTRY(Job) txn_list;
|
|
} Job;
|
|
|
|
/**
|
|
* Callbacks and other information about a Job driver.
|
|
*/
|
|
struct JobDriver {
|
|
/** Derived Job struct size */
|
|
size_t instance_size;
|
|
|
|
/** Enum describing the operation */
|
|
JobType job_type;
|
|
|
|
/** Mandatory: Entrypoint for the Coroutine. */
|
|
CoroutineEntry *start;
|
|
|
|
/**
|
|
* If the callback is not NULL, it will be invoked when the job transitions
|
|
* into the paused state. Paused jobs must not perform any asynchronous
|
|
* I/O or event loop activity. This callback is used to quiesce jobs.
|
|
*/
|
|
void coroutine_fn (*pause)(Job *job);
|
|
|
|
/**
|
|
* If the callback is not NULL, it will be invoked when the job transitions
|
|
* out of the paused state. Any asynchronous I/O or event loop activity
|
|
* should be restarted from this callback.
|
|
*/
|
|
void coroutine_fn (*resume)(Job *job);
|
|
|
|
/**
|
|
* Called when the job is resumed by the user (i.e. user_paused becomes
|
|
* false). .user_resume is called before .resume.
|
|
*/
|
|
void (*user_resume)(Job *job);
|
|
|
|
/**
|
|
* Optional callback for job types whose completion must be triggered
|
|
* manually.
|
|
*/
|
|
void (*complete)(Job *job, Error **errp);
|
|
|
|
/*
|
|
* If the callback is not NULL, it will be invoked when the job has to be
|
|
* synchronously cancelled or completed; it should drain any activities
|
|
* as required to ensure progress.
|
|
*/
|
|
void (*drain)(Job *job);
|
|
|
|
/**
|
|
* If the callback is not NULL, it will be invoked when all the jobs
|
|
* belonging to the same transaction complete; or upon this job's
|
|
* completion if it is not in a transaction. Skipped if NULL.
|
|
*
|
|
* All jobs will complete with a call to either .commit() or .abort() but
|
|
* never both.
|
|
*/
|
|
void (*commit)(Job *job);
|
|
|
|
/**
|
|
* If the callback is not NULL, it will be invoked when any job in the
|
|
* same transaction fails; or upon this job's failure (due to error or
|
|
* cancellation) if it is not in a transaction. Skipped if NULL.
|
|
*
|
|
* All jobs will complete with a call to either .commit() or .abort() but
|
|
* never both.
|
|
*/
|
|
void (*abort)(Job *job);
|
|
|
|
/**
|
|
* If the callback is not NULL, it will be invoked after a call to either
|
|
* .commit() or .abort(). Regardless of which callback is invoked after
|
|
* completion, .clean() will always be called, even if the job does not
|
|
* belong to a transaction group.
|
|
*/
|
|
void (*clean)(Job *job);
|
|
|
|
|
|
/** Called when the job is freed */
|
|
void (*free)(Job *job);
|
|
};
|
|
|
|
typedef enum JobCreateFlags {
|
|
/* Default behavior */
|
|
JOB_DEFAULT = 0x00,
|
|
/* Job is not QMP-created and should not send QMP events */
|
|
JOB_INTERNAL = 0x01,
|
|
/* Job requires manual finalize step */
|
|
JOB_MANUAL_FINALIZE = 0x02,
|
|
/* Job requires manual dismiss step */
|
|
JOB_MANUAL_DISMISS = 0x04,
|
|
} JobCreateFlags;
|
|
|
|
|
|
/**
|
|
* Create a new long-running job and return it.
|
|
*
|
|
* @job_id: The id of the newly-created job, or %NULL for internal jobs
|
|
* @driver: The class object for the newly-created job.
|
|
* @ctx: The AioContext to run the job coroutine in.
|
|
* @flags: Creation flags for the job. See @JobCreateFlags.
|
|
* @cb: Completion function for the job.
|
|
* @opaque: Opaque pointer value passed to @cb.
|
|
* @errp: Error object.
|
|
*/
|
|
void *job_create(const char *job_id, const JobDriver *driver, AioContext *ctx,
|
|
int flags, BlockCompletionFunc *cb, void *opaque, Error **errp);
|
|
|
|
/**
|
|
* Add a reference to Job refcnt, it will be decreased with job_unref, and then
|
|
* be freed if it comes to be the last reference.
|
|
*/
|
|
void job_ref(Job *job);
|
|
|
|
/**
|
|
* Release a reference that was previously acquired with job_ref() or
|
|
* job_create(). If it's the last reference to the object, it will be freed.
|
|
*/
|
|
void job_unref(Job *job);
|
|
|
|
/** To be called when a cancelled job is finalised. */
|
|
void job_event_cancelled(Job *job);
|
|
|
|
/** To be called when a successfully completed job is finalised. */
|
|
void job_event_completed(Job *job);
|
|
|
|
/** To be called when the job transitions to PENDING */
|
|
void job_event_pending(Job *job);
|
|
|
|
/**
|
|
* Conditionally enter the job coroutine if the job is ready to run, not
|
|
* already busy and fn() returns true. fn() is called while under the job_lock
|
|
* critical section.
|
|
*/
|
|
void job_enter_cond(Job *job, bool(*fn)(Job *job));
|
|
|
|
/**
|
|
* @job: A job that has not yet been started.
|
|
*
|
|
* Begins execution of a job.
|
|
* Takes ownership of one reference to the job object.
|
|
*/
|
|
void job_start(Job *job);
|
|
|
|
/**
|
|
* @job: The job to enter.
|
|
*
|
|
* Continue the specified job by entering the coroutine.
|
|
*/
|
|
void job_enter(Job *job);
|
|
|
|
/**
|
|
* @job: The job that is ready to pause.
|
|
*
|
|
* Pause now if job_pause() has been called. Jobs that perform lots of I/O
|
|
* must call this between requests so that the job can be paused.
|
|
*/
|
|
void coroutine_fn job_pause_point(Job *job);
|
|
|
|
/**
|
|
* @job: The job that calls the function.
|
|
* @ns: How many nanoseconds to stop for.
|
|
*
|
|
* Put the job to sleep (assuming that it wasn't canceled) for @ns
|
|
* %QEMU_CLOCK_REALTIME nanoseconds. Canceling the job will immediately
|
|
* interrupt the wait.
|
|
*/
|
|
void coroutine_fn job_sleep_ns(Job *job, int64_t ns);
|
|
|
|
|
|
/** Returns the JobType of a given Job. */
|
|
JobType job_type(const Job *job);
|
|
|
|
/** Returns the enum string for the JobType of a given Job. */
|
|
const char *job_type_str(const Job *job);
|
|
|
|
/** Returns whether the job is scheduled for cancellation. */
|
|
bool job_is_cancelled(Job *job);
|
|
|
|
/** Returns whether the job is in a completed state. */
|
|
bool job_is_completed(Job *job);
|
|
|
|
/**
|
|
* Request @job to pause at the next pause point. Must be paired with
|
|
* job_resume(). If the job is supposed to be resumed by user action, call
|
|
* job_user_pause() instead.
|
|
*/
|
|
void job_pause(Job *job);
|
|
|
|
/** Resumes a @job paused with job_pause. */
|
|
void job_resume(Job *job);
|
|
|
|
/**
|
|
* Asynchronously pause the specified @job.
|
|
* Do not allow a resume until a matching call to job_user_resume.
|
|
*/
|
|
void job_user_pause(Job *job, Error **errp);
|
|
|
|
/** Returns true if the job is user-paused. */
|
|
bool job_user_paused(Job *job);
|
|
|
|
/**
|
|
* Resume the specified @job.
|
|
* Must be paired with a preceding job_user_pause.
|
|
*/
|
|
void job_user_resume(Job *job, Error **errp);
|
|
|
|
/*
|
|
* Drain any activities as required to ensure progress. This can be called in a
|
|
* loop to synchronously complete a job.
|
|
*/
|
|
void job_drain(Job *job);
|
|
|
|
/**
|
|
* Get the next element from the list of block jobs after @job, or the
|
|
* first one if @job is %NULL.
|
|
*
|
|
* Returns the requested job, or %NULL if there are no more jobs left.
|
|
*/
|
|
Job *job_next(Job *job);
|
|
|
|
/**
|
|
* Get the job identified by @id (which must not be %NULL).
|
|
*
|
|
* Returns the requested job, or %NULL if it doesn't exist.
|
|
*/
|
|
Job *job_get(const char *id);
|
|
|
|
/**
|
|
* Check whether the verb @verb can be applied to @job in its current state.
|
|
* Returns 0 if the verb can be applied; otherwise errp is set and -EPERM
|
|
* returned.
|
|
*/
|
|
int job_apply_verb(Job *job, JobVerb verb, Error **errp);
|
|
|
|
/** The @job could not be started, free it. */
|
|
void job_early_fail(Job *job);
|
|
|
|
/** Asynchronously complete the specified @job. */
|
|
void job_complete(Job *job, Error **errp);;
|
|
|
|
typedef void JobDeferToMainLoopFn(Job *job, void *opaque);
|
|
|
|
/**
|
|
* @job: The job
|
|
* @fn: The function to run in the main loop
|
|
* @opaque: The opaque value that is passed to @fn
|
|
*
|
|
* This function must be called by the main job coroutine just before it
|
|
* returns. @fn is executed in the main loop with the job AioContext acquired.
|
|
*
|
|
* Block jobs must call bdrv_unref(), bdrv_close(), and anything that uses
|
|
* bdrv_drain_all() in the main loop.
|
|
*
|
|
* The @job AioContext is held while @fn executes.
|
|
*/
|
|
void job_defer_to_main_loop(Job *job, JobDeferToMainLoopFn *fn, void *opaque);
|
|
|
|
/**
|
|
* Synchronously finishes the given @job. If @finish is given, it is called to
|
|
* trigger completion or cancellation of the job.
|
|
*
|
|
* Returns 0 if the job is successfully completed, -ECANCELED if the job was
|
|
* cancelled before completing, and -errno in other error cases.
|
|
*/
|
|
int job_finish_sync(Job *job, void (*finish)(Job *, Error **errp), Error **errp);
|
|
|
|
/* TODO To be removed from the public interface */
|
|
void job_state_transition(Job *job, JobStatus s1);
|
|
void coroutine_fn job_do_yield(Job *job, uint64_t ns);
|
|
bool job_should_pause(Job *job);
|
|
bool job_started(Job *job);
|
|
void job_do_dismiss(Job *job);
|
|
int job_finalize_single(Job *job);
|
|
void job_update_rc(Job *job);
|
|
|
|
typedef struct BlockJob BlockJob;
|
|
void block_job_txn_del_job(BlockJob *job);
|
|
|
|
#endif
|