* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
+
#ifndef BLOCKJOB_H
-#define BLOCKJOB_H 1
+#define BLOCKJOB_H
#include "block/block.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);
-
- /**
- * Optional callback for job types whose completion must be triggered
- * manually.
- */
- void (*complete)(BlockJob *job, Error **errp);
-} BlockJobDriver;
+typedef struct BlockJobDriver BlockJobDriver;
+typedef struct BlockJobTxn BlockJobTxn;
/**
* BlockJob:
*
* Long-running operation on a BlockDriverState.
*/
-struct BlockJob {
+typedef struct BlockJob {
/** The job type, including the job vtable. */
const BlockJobDriver *driver;
/** The block device on which the job is operating. */
- BlockDriverState *bs;
+ BlockBackend *blk;
+
+ /**
+ * The ID of the block job. May be NULL for internal jobs.
+ */
+ char *id;
/**
* The coroutine that executes the job. If not NULL, it is
bool cancelled;
/**
- * Set to true if the job is either paused, or will pause itself
- * as soon as possible (if busy == true).
+ * Counter for pause request. If non-zero, the block job is either paused,
+ * or if busy == true will pause itself as soon as possible.
*/
- bool paused;
+ int pause_count;
+
+ /**
+ * 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 false by the job while it is in a quiescent state, where
- * no I/O is pending and the job has yielded on any condition
- * that is not detected by #aio_poll, such as a timer.
+ * 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.
*/
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 when the job is ready to be completed.
+ */
+ bool ready;
+
+ /**
+ * Set to true when the job has deferred work to the main loop.
+ */
+ 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;
/** 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.
+ */
+ bool completed;
+
+ /* ret code passed to block_job_completed.
+ */
+ int ret;
+
+ /** Non-NULL if this job is part of a transaction */
+ BlockJobTxn *txn;
+ QLIST_ENTRY(BlockJob) txn_list;
+} BlockJob;
+
+typedef enum BlockJobCreateFlags {
+ BLOCK_JOB_DEFAULT = 0x00,
+ BLOCK_JOB_INTERNAL = 0x01,
+} BlockJobCreateFlags;
/**
- * block_job_create:
- * @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.
+ * block_job_next:
+ * @job: A block job, or %NULL.
*
- * 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.
+ * Get the next element from the list of block jobs after @job, or the
+ * first one if @job is %NULL.
*
- * This function is not part of the public job interface; it should be
- * called from a wrapper that is specific to the job type.
+ * Returns the requested job, or %NULL if there are no more jobs left.
*/
-void *block_job_create(const BlockJobDriver *driver, BlockDriverState *bs,
- int64_t speed, BlockCompletionFunc *cb,
- void *opaque, Error **errp);
+BlockJob *block_job_next(BlockJob *job);
/**
- * block_job_sleep_ns:
- * @job: The job that calls the function.
- * @clock: The clock to sleep on.
- * @ns: How many nanoseconds to stop for.
+ * block_job_get:
+ * @id: The id of the block job.
+ *
+ * Get the block job identified by @id (which must not be %NULL).
*
- * Put the job to sleep (assuming that it wasn't canceled) for @ns
- * nanoseconds. Canceling the job will interrupt the wait immediately.
+ * Returns the requested job, or %NULL if it doesn't exist.
*/
-void block_job_sleep_ns(BlockJob *job, QEMUClockType type, int64_t ns);
+BlockJob *block_job_get(const char *id);
/**
- * block_job_yield:
- * @job: The job that calls the function.
+ * 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
*
- * Yield the block job coroutine.
+ * 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_yield(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.
*/
void block_job_complete(BlockJob *job, Error **errp);
-/**
- * block_job_is_cancelled:
- * @job: The job being queried.
- *
- * Returns whether the job is scheduled for cancellation.
- */
-bool block_job_is_cancelled(BlockJob *job);
-
/**
* block_job_query:
* @job: The job to get information about.
*
* Return information about a job.
*/
-BlockJobInfo *block_job_query(BlockJob *job);
+BlockJobInfo *block_job_query(BlockJob *job, Error **errp);
/**
* block_job_pause:
void block_job_pause(BlockJob *job);
/**
- * block_job_resume:
- * @job: The job to be resumed.
- *
- * Resume the specified job.
- */
-void block_job_resume(BlockJob *job);
-
-/**
- * block_job_event_cancelled:
- * @job: The job whose information is requested.
+ * block_job_user_pause:
+ * @job: The job to be paused.
*
- * Send a BLOCK_JOB_CANCELLED event for the specified job.
+ * Asynchronously pause the specified job.
+ * Do not allow a resume until a matching call to block_job_user_resume.
*/
-void block_job_event_cancelled(BlockJob *job);
+void block_job_user_pause(BlockJob *job);
/**
- * block_job_ready:
- * @job: The job which is now ready to complete.
- * @msg: Error message. Only present on failure.
+ * block_job_paused:
+ * @job: The job to query.
*
- * Send a BLOCK_JOB_COMPLETED event for the specified job.
+ * Returns true if the job is user-paused.
*/
-void block_job_event_completed(BlockJob *job, const char *msg);
+bool block_job_user_paused(BlockJob *job);
/**
- * block_job_ready:
- * @job: The job which is now ready to complete.
+ * block_job_resume:
+ * @job: The job to be resumed.
*
- * Send a BLOCK_JOB_READY event for the specified job.
+ * Resume the specified job. Must be paired with a preceding block_job_pause.
*/
-void block_job_event_ready(BlockJob *job);
+void block_job_resume(BlockJob *job);
/**
- * block_job_is_paused:
- * @job: The job being queried.
+ * block_job_user_resume:
+ * @job: The job to be resumed.
*
- * Returns whether the job is currently paused, or will pause
- * as soon as it reaches a sleeping point.
+ * Resume the specified job.
+ * Must be paired with a preceding block_job_user_pause.
*/
-bool block_job_is_paused(BlockJob *job);
+void block_job_user_resume(BlockJob *job);
/**
* block_job_cancel_sync:
*/
int block_job_cancel_sync(BlockJob *job);
+/**
+ * block_job_cancel_sync_all:
+ *
+ * Synchronously cancels all jobs using block_job_cancel_sync().
+ */
+void block_job_cancel_sync_all(void);
+
+/**
+ * block_job_complete_sync:
+ * @job: The job to be completed.
+ * @errp: Error object which may be set by block_job_complete(); this is not
+ * necessarily set on every error, the job return value has to be
+ * checked as well.
+ *
+ * Synchronously complete the job. The completion callback is called before the
+ * function returns, unless it is NULL (which is permissible when using this
+ * function).
+ *
+ * Returns the return value from the job.
+ */
+int block_job_complete_sync(BlockJob *job, Error **errp);
+
/**
* block_job_iostatus_reset:
* @job: The job whose I/O status should be reset.
*
* Reset I/O status on @job and on BlockDriverState objects it uses,
- * other than job->bs.
+ * other than job->blk.
*/
void block_job_iostatus_reset(BlockJob *job);
/**
- * block_job_error_action:
- * @job: The job to signal an error for.
- * @bs: The block device on which to set an I/O error.
- * @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.
+ * block_job_txn_new:
+ *
+ * Allocate and return a new block job transaction. Jobs can be added to the
+ * transaction using block_job_txn_add_job().
+ *
+ * The transaction is automatically freed when the last job completes or is
+ * cancelled.
+ *
+ * All jobs in the transaction either complete successfully or fail/cancel as a
+ * group. Jobs wait for each other before completing. Cancelling one job
+ * cancels all jobs in the transaction.
*/
-BlockErrorAction block_job_error_action(BlockJob *job, BlockDriverState *bs,
- BlockdevOnError on_err,
- int is_read, int error);
+BlockJobTxn *block_job_txn_new(void);
+
+/**
+ * block_job_txn_unref:
+ *
+ * Release a reference that was previously acquired with block_job_txn_add_job
+ * or block_job_txn_new. If it's the last reference to the object, it will be
+ * freed.
+ */
+void block_job_txn_unref(BlockJobTxn *txn);
+
+/**
+ * block_job_txn_add_job:
+ * @txn: The transaction (may be NULL)
+ * @job: Job to add to the transaction
+ *
+ * Add @job to the transaction. The @job must not already be in a transaction.
+ * The caller must call either block_job_txn_unref() or block_job_completed()
+ * to release the reference that is automatically grabbed here.
+ */
+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);
+
#endif
projects / qemu.git / blobdiff