diff options
Diffstat (limited to 'include/block/blockjob.h')
| -rw-r--r-- | include/block/blockjob.h | 256 |
1 files changed, 37 insertions, 219 deletions
diff --git a/include/block/blockjob.h b/include/block/blockjob.h index 4dfb16b43f..356cacf004 100644 --- a/include/block/blockjob.h +++ b/include/block/blockjob.h @@ -28,85 +28,15 @@ #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); - - /** - * 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); - - /* - * If the callback is not NULL, it will be invoked when the job has to be - * synchronously cancelled or completed; it should drain BlockDriverStates - * as required to ensure progress. - */ - void (*drain)(BlockJob *job); -} 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; @@ -114,7 +44,7 @@ struct BlockJob { BlockBackend *blk; /** - * The ID of the block job. + * The ID of the block job. May be NULL for internal jobs. */ char *id; @@ -208,7 +138,12 @@ struct BlockJob { /** 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_next: @@ -232,30 +167,6 @@ BlockJob *block_job_next(BlockJob *job); 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_add_bdrv: * @job: A block job * @bs: A BlockDriverState that is involved in @job @@ -267,52 +178,6 @@ void *block_job_create(const char *job_id, const BlockJobDriver *driver, void block_job_add_bdrv(BlockJob *job, BlockDriverState *bs); /** - * 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. - * - * Release reference to the block job and release resources if it is the last - * reference. - */ -void block_job_unref(BlockJob *job); - -/** - * block_job_completed: - * @job: The job being completed. - * @ret: The status code. - * - * Call the completion function that was registered at creation time, and - * free @job. - */ -void block_job_completed(BlockJob *job, int ret); - -/** * block_job_set_speed: * @job: The job to set the speed for. * @speed: The new value @@ -341,29 +206,12 @@ void block_job_cancel(BlockJob *job); 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); - -/** - * block_job_pause_point: - * @job: The job that is ready to pause. - * - * 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. - */ -void coroutine_fn block_job_pause_point(BlockJob *job); +BlockJobInfo *block_job_query(BlockJob *job, Error **errp); /** * block_job_pause: @@ -374,45 +222,38 @@ void coroutine_fn block_job_pause_point(BlockJob *job); void block_job_pause(BlockJob *job); /** - * block_job_resume: - * @job: The job to be resumed. - * - * Resume the specified job. Must be paired with a preceding block_job_pause. - */ -void block_job_resume(BlockJob *job); - -/** - * 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); /** - * 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_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_pause. */ -void block_job_event_completed(BlockJob *job, const char *msg); +void block_job_resume(BlockJob *job); /** - * block_job_ready: - * @job: The job which is now ready to complete. + * block_job_user_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_user_pause. */ -void block_job_event_ready(BlockJob *job); +void block_job_user_resume(BlockJob *job); /** * block_job_cancel_sync: @@ -460,37 +301,6 @@ int block_job_complete_sync(BlockJob *job, Error **errp); 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: * * Allocate and return a new block job transaction. Jobs can be added to the @@ -525,4 +335,12 @@ void block_job_txn_unref(BlockJobTxn *txn); */ 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 |