#ifndef BLOCKJOB_H
#define BLOCKJOB_H
+#include "qemu/job.h"
#include "block/block.h"
+#include "qemu/ratelimit.h"
-/**
- * BlockJobDriver:
- *
- * A class type for block job driver.
- */
-typedef struct BlockJobDriver {
- /** Derived BlockJob struct size */
- size_t instance_size;
-
- /** String describing the operation, part of query-block-jobs QMP API */
- BlockJobType job_type;
-
- /** Optional callback for job types that support setting a speed limit */
- void (*set_speed)(BlockJob *job, int64_t speed, Error **errp);
-
- /** Optional callback for job types that need to forward I/O status reset */
- void (*iostatus_reset)(BlockJob *job);
+#define BLOCK_JOB_SLICE_TIME 100000000ULL /* ns */
- /**
- * Optional callback for job types whose completion must be triggered
- * manually.
- */
- void (*complete)(BlockJob *job, Error **errp);
-
- /**
- * 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)(BlockJob *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)(BlockJob *job);
-
- /**
- * 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)(BlockJob *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)(BlockJob *job);
-
- /*
- * If the callback is not NULL, it will be invoked before the job is
- * resumed in a new AioContext. This is the place to move any resources
- * besides job->blk to the new AioContext.
- */
- void (*attached_aio_context)(BlockJob *job, AioContext *new_context);
-} BlockJobDriver;
+typedef struct BlockJobDriver BlockJobDriver;
+typedef struct BlockJobTxn BlockJobTxn;
/**
* BlockJob:
*
* Long-running operation on a BlockDriverState.
*/
-struct BlockJob {
+typedef struct BlockJob {
+ /** Data belonging to the generic Job infrastructure */
+ Job job;
+
/** The job type, including the job vtable. */
const BlockJobDriver *driver;
/** The block device on which the job is operating. */
BlockBackend *blk;
- /**
- * The ID of the block job.
- */
- char *id;
-
/**
* The coroutine that executes the job. If not NULL, it is
* reentered when busy is false and the job is cancelled.
Coroutine *co;
/**
- * 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.
+ * Set to true if the job should abort immediately without waiting
+ * for data to be in sync.
*/
- bool cancelled;
+ bool force;
/**
* Counter for pause request. If non-zero, the block job is either paused,
/**
* 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.
+ * activity pending. Accessed under block_job_mutex (in blockjob.c).
*/
bool busy;
*/
bool deferred_to_main_loop;
- /** Element of the list of block jobs */
- QLIST_ENTRY(BlockJob) job_list;
-
/** Status that is published by the query-block-jobs QMP API */
BlockDeviceIoStatus iostatus;
/** Speed that was set with @block_job_set_speed. */
int64_t speed;
+ /** Rate limiting data structure for implementing @speed. */
+ RateLimit limit;
+
/** The completion function that will be called when the job completes. */
BlockCompletionFunc *cb;
/** Block other operations when block job is running */
Error *blocker;
+ /** BlockDriverStates that are involved in this block job */
+ GSList *nodes;
+
/** The opaque value that is passed to the completion function. */
void *opaque;
- /** Reference count of the block job */
- int refcnt;
-
- /* True if this job has reported completion by calling block_job_completed.
- */
+ /** True when job has reported completion by calling block_job_completed. */
bool completed;
- /* ret code passed to block_job_completed.
- */
+ /** ret code passed to block_job_completed. */
int ret;
- /** Non-NULL if this job is part of a transaction */
+ /**
+ * Timer that is used by @block_job_sleep_ns. Accessed under
+ * block_job_mutex (in blockjob.c).
+ */
+ QEMUTimer sleep_timer;
+
+ /** True if this job should automatically finalize itself */
+ bool auto_finalize;
+
+ /** True if this job should automatically dismiss itself */
+ bool auto_dismiss;
+
BlockJobTxn *txn;
QLIST_ENTRY(BlockJob) txn_list;
-};
+} BlockJob;
+
+typedef enum BlockJobCreateFlags {
+ /* Default behavior */
+ BLOCK_JOB_DEFAULT = 0x00,
+ /* BlockJob is not QMP-created and should not send QMP events */
+ BLOCK_JOB_INTERNAL = 0x01,
+ /* BlockJob requires manual finalize step */
+ BLOCK_JOB_MANUAL_FINALIZE = 0x02,
+ /* BlockJob requires manual dismiss step */
+ BLOCK_JOB_MANUAL_DISMISS = 0x04,
+} BlockJobCreateFlags;
/**
* block_job_next:
BlockJob *block_job_get(const char *id);
/**
- * block_job_create:
- * @job_id: The id of the newly-created job, or %NULL to have one
- * generated automatically.
- * @job_type: The class object for the newly-created job.
- * @bs: The block
- * @speed: The maximum speed, in bytes per second, or 0 for unlimited.
- * @cb: Completion function for the job.
- * @opaque: Opaque pointer value passed to @cb.
- * @errp: Error object.
- *
- * Create a new long-running block device job and return it. The job
- * will call @cb asynchronously when the job completes. Note that
- * @bs may have been closed at the time the @cb it is called. If
- * this is the case, the job may be reported as either cancelled or
- * completed.
- *
- * This function is not part of the public job interface; it should be
- * called from a wrapper that is specific to the job type.
- */
-void *block_job_create(const char *job_id, const BlockJobDriver *driver,
- BlockDriverState *bs, int64_t speed,
- BlockCompletionFunc *cb, void *opaque, Error **errp);
-
-/**
- * block_job_sleep_ns:
- * @job: The job that calls the function.
- * @clock: The clock to sleep on.
- * @ns: How many nanoseconds to stop for.
- *
- * Put the job to sleep (assuming that it wasn't canceled) for @ns
- * nanoseconds. Canceling the job will interrupt the wait immediately.
- */
-void block_job_sleep_ns(BlockJob *job, QEMUClockType type, int64_t ns);
-
-/**
- * block_job_yield:
- * @job: The job that calls the function.
- *
- * Yield the block job coroutine.
- */
-void block_job_yield(BlockJob *job);
-
-/**
- * block_job_ref:
- * @bs: The block device.
- *
- * Grab a reference to the block job. Should be paired with block_job_unref.
- */
-void block_job_ref(BlockJob *job);
-
-/**
- * block_job_unref:
- * @bs: The block device.
+ * block_job_add_bdrv:
+ * @job: A block job
+ * @name: The name to assign to the new BdrvChild
+ * @bs: A BlockDriverState that is involved in @job
+ * @perm, @shared_perm: Permissions to request on the node
*
- * Release reference to the block job and release resources if it is the last
- * reference.
+ * Add @bs to the list of BlockDriverState that are involved in
+ * @job. This means that all operations will be blocked on @bs while
+ * @job exists.
*/
-void block_job_unref(BlockJob *job);
+int block_job_add_bdrv(BlockJob *job, const char *name, BlockDriverState *bs,
+ uint64_t perm, uint64_t shared_perm, Error **errp);
/**
- * block_job_completed:
- * @job: The job being completed.
- * @ret: The status code.
+ * block_job_remove_all_bdrv:
+ * @job: The block job
*
- * Call the completion function that was registered at creation time, and
- * free @job.
+ * Remove all BlockDriverStates from the list of nodes that are involved in the
+ * job. This removes the blockers added with block_job_add_bdrv().
*/
-void block_job_completed(BlockJob *job, int ret);
+void block_job_remove_all_bdrv(BlockJob *job);
/**
* block_job_set_speed:
*/
void block_job_set_speed(BlockJob *job, int64_t speed, Error **errp);
+/**
+ * block_job_start:
+ * @job: A job that has not yet been started.
+ *
+ * Begins execution of a block job.
+ * Takes ownership of one reference to the job object.
+ */
+void block_job_start(BlockJob *job);
+
/**
* block_job_cancel:
* @job: The job to be canceled.
+ * @force: Quit a job without waiting for data to be in sync.
*
* Asynchronously cancel the specified job.
*/
-void block_job_cancel(BlockJob *job);
+void block_job_cancel(BlockJob *job, bool force);
/**
* block_job_complete:
*/
void block_job_complete(BlockJob *job, Error **errp);
+
/**
- * block_job_is_cancelled:
- * @job: The job being queried.
+ * block_job_finalize:
+ * @job: The job to fully commit and finish.
+ * @errp: Error object.
*
- * Returns whether the job is scheduled for cancellation.
+ * For jobs that have finished their work and are pending
+ * awaiting explicit acknowledgement to commit their work,
+ * This will commit that work.
+ *
+ * FIXME: Make the below statement universally true:
+ * For jobs that support the manual workflow mode, all graph
+ * changes that occur as a result will occur after this command
+ * and before a successful reply.
*/
-bool block_job_is_cancelled(BlockJob *job);
+void block_job_finalize(BlockJob *job, Error **errp);
/**
- * block_job_query:
- * @job: The job to get information about.
+ * block_job_dismiss:
+ * @job: The job to be dismissed.
+ * @errp: Error object.
*
- * Return information about a job.
+ * Remove a concluded job from the query list.
*/
-BlockJobInfo *block_job_query(BlockJob *job);
+void block_job_dismiss(BlockJob **job, Error **errp);
/**
- * block_job_pause_point:
- * @job: The job that is ready to pause.
+ * block_job_progress_update:
+ * @job: The job that has made progress
+ * @done: How much progress the job made
*
- * Pause now if block_job_pause() has been called. Block jobs that perform
- * lots of I/O must call this between requests so that the job can be paused.
+ * Updates the progress counter of the job.
*/
-void coroutine_fn block_job_pause_point(BlockJob *job);
+void block_job_progress_update(BlockJob *job, uint64_t done);
/**
- * block_job_pause:
- * @job: The job to be paused.
+ * block_job_progress_set_remaining:
+ * @job: The job whose expected progress end value is set
+ * @remaining: Expected end value of the progress counter of the job
*
- * Asynchronously pause the specified job.
+ * Sets the expected end value of the progress counter of a job so that a
+ * completion percentage can be calculated when the progress is updated.
*/
-void block_job_pause(BlockJob *job);
+void block_job_progress_set_remaining(BlockJob *job, uint64_t remaining);
/**
- * block_job_resume:
- * @job: The job to be resumed.
+ * block_job_query:
+ * @job: The job to get information about.
*
- * Resume the specified job. Must be paired with a preceding block_job_pause.
+ * Return information about a job.
*/
-void block_job_resume(BlockJob *job);
+BlockJobInfo *block_job_query(BlockJob *job, Error **errp);
/**
- * block_job_enter:
- * @job: The job to enter.
+ * block_job_user_pause:
+ * @job: The job to be paused.
*
- * Continue the specified job by entering the coroutine.
+ * Asynchronously pause the specified job.
+ * Do not allow a resume until a matching call to block_job_user_resume.
*/
-void block_job_enter(BlockJob *job);
+void block_job_user_pause(BlockJob *job, Error **errp);
/**
- * block_job_event_cancelled:
- * @job: The job whose information is requested.
+ * block_job_paused:
+ * @job: The job to query.
*
- * Send a BLOCK_JOB_CANCELLED event for the specified job.
+ * Returns true if the job is user-paused.
*/
-void block_job_event_cancelled(BlockJob *job);
+bool block_job_user_paused(BlockJob *job);
/**
- * block_job_ready:
- * @job: The job which is now ready to complete.
- * @msg: Error message. Only present on failure.
+ * block_job_user_resume:
+ * @job: The job to be resumed.
*
- * Send a BLOCK_JOB_COMPLETED event for the specified job.
+ * Resume the specified job.
+ * Must be paired with a preceding block_job_user_pause.
*/
-void block_job_event_completed(BlockJob *job, const char *msg);
+void block_job_user_resume(BlockJob *job, Error **errp);
/**
- * block_job_ready:
- * @job: The job which is now ready to complete.
+ * block_job_user_cancel:
+ * @job: The job to be cancelled.
+ * @force: Quit a job without waiting for data to be in sync.
*
- * Send a BLOCK_JOB_READY event for the specified job.
+ * Cancels the specified job, but may refuse to do so if the
+ * operation isn't currently meaningful.
*/
-void block_job_event_ready(BlockJob *job);
+void block_job_user_cancel(BlockJob *job, bool force, Error **errp);
/**
* block_job_cancel_sync:
*/
void block_job_iostatus_reset(BlockJob *job);
-/**
- * block_job_error_action:
- * @job: The job to signal an error for.
- * @on_err: The error action setting.
- * @is_read: Whether the operation was a read.
- * @error: The error that was reported.
- *
- * Report an I/O error for a block job and possibly stop the VM. Return the
- * action that was selected based on @on_err and @error.
- */
-BlockErrorAction block_job_error_action(BlockJob *job, BlockdevOnError on_err,
- int is_read, int error);
-
-typedef void BlockJobDeferToMainLoopFn(BlockJob *job, void *opaque);
-
-/**
- * block_job_defer_to_main_loop:
- * @job: The job
- * @fn: The function to run in the main loop
- * @opaque: The opaque value that is passed to @fn
- *
- * Execute a given function in the main loop with the BlockDriverState
- * 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 block_job_defer_to_main_loop(BlockJob *job,
- BlockJobDeferToMainLoopFn *fn,
- void *opaque);
-
/**
* block_job_txn_new:
*
*/
void block_job_txn_add_job(BlockJobTxn *txn, BlockJob *job);
+/**
+ * block_job_is_internal:
+ * @job: The job to determine if it is user-visible or not.
+ *
+ * Returns true if the job should not be visible to the management layer.
+ */
+bool block_job_is_internal(BlockJob *job);
+
+/**
+ * block_job_driver:
+ *
+ * Returns the driver associated with a block job.
+ */
+const BlockJobDriver *block_job_driver(BlockJob *job);
+
#endif
projects / qemu.git / blobdiff