job header

The documentation of QEMU’s qemu/job.h header.

JobTxn * job_txn_new(void)

Parameters

void

no arguments

Description

transaction using 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.

void job_txn_unref(JobTxn * txn)

Parameters

JobTxn * txn

undescribed

Description

job_txn_new. If it’s the last reference to the object, it will be freed.

void * job_create(const char * job_id, const JobDriver * driver, JobTxn * txn, AioContext * ctx, int flags, BlockCompletionFunc * cb, void * opaque, Error ** errp)

running job and return it.

Parameters

const char * job_id

The id of the newly-created job, or NULL for internal jobs

const JobDriver * driver

The class object for the newly-created job.

JobTxn * txn

The transaction this job belongs to, if any. NULL otherwise.

AioContext * ctx

The AioContext to run the job coroutine in.

int flags

Creation flags for the job. See JobCreateFlags.

BlockCompletionFunc * cb

Completion function for the job.

void * opaque

Opaque pointer value passed to cb.

Error ** errp

Error object.

void job_ref(Job * job)

Parameters

Job * job

undescribed

Description

be freed if it comes to be the last reference.

void job_unref(Job * job)

Parameters

Job * job

undescribed

Description

job_create(). If it’s the last reference to the object, it will be freed.

void job_enter_cond(Job * job, bool(*fn) (Job *job)

Parameters

Job * job

undescribed

bool(*)(Job *job) fn

undescribed

Description

already busy and fn() returns true. fn() is called while under the job_lock critical section.

void job_pause(Job * job)

Parameters

Job * job

undescribed

Description

job_resume(). If the job is supposed to be resumed by user action, call job_user_pause() instead.

void job_user_pause(Job * job, Error ** errp)

Parameters

Job * job

undescribed

Error ** errp

undescribed

Description

Do not allow a resume until a matching call to job_user_resume.

void job_user_resume(Job * job, Error ** errp)

Parameters

Job * job

undescribed

Error ** errp

undescribed

Description

Must be paired with a preceding job_user_pause.

Job * job_next(Job * job)

Parameters

Job * job

undescribed

Description

first one if job is NULL.

Returns the requested job, or NULL if there are no more jobs left.

Job * job_get(const char * id)

Parameters

const char * id

undescribed

Description

Returns the requested job, or NULL if it doesn’t exist.

int job_apply_verb(Job * job, JobVerb verb, Error ** errp)

Parameters

Job * job

undescribed

JobVerb verb

undescribed

Error ** errp

undescribed

Description

Returns 0 if the verb can be applied; otherwise errp is set and -EPERM returned.

void job_cancel(Job * job, bool force)

Parameters

Job * job

undescribed

bool force

undescribed

Description

be cancelled immediately without waiting for a consistent state.

void job_user_cancel(Job * job, bool force, Error ** errp)

Parameters

Job * job

undescribed

bool force

undescribed

Error ** errp

undescribed

Description

operation isn’t meaningful in the current state of the job.

int job_cancel_sync(Job * job)

Parameters

Job * job

undescribed

Description

before the function returns. The job may actually complete instead of canceling itself; the circumstances under which this happens depend on the kind of job that is active.

Returns the return value from the job if the job actually completed during the call, or -ECANCELED if it was canceled.

Callers must hold the AioContext lock of job->aio_context.

void job_finalize(Job * job, Error ** errp)

Parameters

Job * job

undescribed

Error ** errp

undescribed

Description

acknowledgement to commit its 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.

void job_dismiss(Job ** job, Error ** errp)

Parameters

Job ** job

undescribed

Error ** errp

undescribed

Description

to NULL. Returns an error if the job is not actually concluded.

int job_finish_sync(Job * job, void (*finish) (Job *, Error **errp, Error ** errp)

Parameters

Job * job

undescribed

void (*)(Job *, Error **errp) finish

undescribed

Error ** errp

undescribed

Description

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.

Callers must hold the AioContext lock of job->aio_context.