Description

Provides functions to manage jobs on a device.

A job is a task submitted to a device for execution. Most jobs are quantum circuits to be executed on a quantum device. However, jobs can also be a different type of task, such as calibration.

The typical workflow for a device job is as follows:

Create a job with QDMI_device_session_create_device_job.
Set parameters for the job with QDMI_device_job_set_parameter.
Submit the job with QDMI_device_job_submit.
Check the status of the job with QDMI_device_job_check.
Wait for the job to finish with QDMI_device_job_wait.
Retrieve the results of the job with QDMI_device_job_get_results.
Free the job with QDMI_device_job_free when it is no longer used.

Typedefs
typedef struct QDMI_Device_Job_impl_d *	QDMI_Device_Job
	A handle for a device job.

Functions
int	QDMI_device_session_create_device_job (QDMI_Device_Session session, QDMI_Device_Job *job)
	Create a job.

int	QDMI_device_job_set_parameter (QDMI_Device_Job job, QDMI_Device_Job_Parameter param, size_t size, const void *value)
	Set a parameter for a job.

int	QDMI_device_job_submit (QDMI_Device_Job job)
	Submit a job to the device.

int	QDMI_device_job_cancel (QDMI_Device_Job job)
	Cancel an already submitted job.

int	QDMI_device_job_check (QDMI_Device_Job job, QDMI_Job_Status *status)
	Check the status of a job.

int	QDMI_device_job_wait (QDMI_Device_Job job)
	Wait for a job to finish.

int	QDMI_device_job_get_results (QDMI_Device_Job job, QDMI_Job_Result result, size_t size, void data, size_t size_ret)
	Retrieve the results of a job.

void	QDMI_device_job_free (QDMI_Device_Job job)
	Free a job.

Typedef Documentation

◆ QDMI_Device_Job

typedef struct QDMI_Device_Job_impl_d* QDMI_Device_Job

A handle for a device job.

An opaque pointer to a type defined by the device that encapsulates all information about a job on a device.

Remarks: Implementations of the underlying type will want to store the session handle used to create the job in the job handle to be able to access the session information when needed.

See also: QDMI_Job for the client-side job handle.

Function Documentation

◆ QDMI_device_session_create_device_job()

int QDMI_device_session_create_device_job	(	QDMI_Device_Session	session,
		QDMI_Device_Job *	job )

Create a job.

This is the main entry point for a driver to create a job for a device. The returned handle can be used throughout the device job interface to refer to the job.

Parameters

[in]	session	The session to create the job on. Must not be `NULL`.
[out]	job	A pointer to a handle that will store the created job. Must not be `NULL`. The job must be freed by calling QDMI_device_job_free when it is no longer used.

Returns: QDMI_SUCCESS if the job was successfully created.; QDMI_ERROR_INVALIDARGUMENT if session or job are NULL.; QDMI_ERROR_BADSTATE if the session is not in a state allowing the creation of a job, for example, because the session is not initialized.; QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.; QDMI_ERROR_FATAL if job creation failed due to a fatal error.

Attention: May only be called after the session has been initialized with QDMI_device_session_init.

◆ QDMI_device_job_set_parameter()

int QDMI_device_job_set_parameter	(	QDMI_Device_Job	job,
		QDMI_Device_Job_Parameter	param,
		size_t	size,
		const void *	value )

Set a parameter for a job.

Parameters

[in]	job	A handle to a job for which to set `param`. Must not be `NULL`.
[in]	param	The parameter whose value will be set. Must be one of the values specified for QDMI_Device_Job_Parameter.
[in]	size	The size of the data pointed to by `value` in bytes. Must not be zero, except when `value` is `NULL`, in which case it is ignored.
[in]	value	A pointer to the memory location that contains the value of the parameter to be set. The data pointed to by `value` is copied and can be safely reused after this function returns. If this is `NULL`, it is ignored.

Returns

QDMI_SUCCESS if the device supports the specified QDMI_Device_Job_Parameter param and, when value is not NULL, the parameter was successfully set.

QDMI_ERROR_NOTSUPPORTED if the device does not support the parameter or the value of the parameter.

QDMI_ERROR_INVALIDARGUMENT if

job is NULL,
param is invalid, or
value is not NULL and size is zero or not the expected size for the parameter (if specified by the QDMI_Device_Job_Parameter documentation).

QDMI_ERROR_BADSTATE if the parameter cannot be set in the current state of the job, for example, because the job is already submitted.

QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.

QDMI_ERROR_FATAL if setting the parameter failed due to a fatal error.

Remarks: Calling this function with value set to NULL is expected to allow checking if the device supports the specified parameter without setting the parameter and without the need to provide a value. See the QDMI_job_set_parameter documentation for an example.

◆ QDMI_device_job_submit()

int QDMI_device_job_submit ( QDMI_Device_Job job )

Submit a job to the device.

This function can either be blocking until the job is finished or non-blocking and return while the job is running. In the latter case, the functions QDMI_device_job_check and QDMI_device_job_wait can be used to check the status and wait for the job to finish.

Parameters

[in] job The job to submit. Must not be NULL.

Returns: QDMI_SUCCESS if the job was successfully submitted.; QDMI_ERROR_INVALIDARGUMENT if job is NULL.; QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.; QDMI_ERROR_FATAL if the job submission failed.

◆ QDMI_device_job_cancel()

int QDMI_device_job_cancel ( QDMI_Device_Job job )

Cancel an already submitted job.

Remove the job from the queue of waiting jobs. This changes the status of the job to QDMI_JOB_STATUS_CANCELED.

Parameters

[in] job The job to cancel. Must not be NULL.

Returns: QDMI_SUCCESS if the job was successfully canceled.; QDMI_ERROR_INVALIDARGUMENT if job is NULL or the job already has the status QDMI_JOB_STATUS_DONE.; QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.; QDMI_ERROR_FATAL if the job could not be canceled.

◆ QDMI_device_job_check()

int QDMI_device_job_check	(	QDMI_Device_Job	job,
		QDMI_Job_Status *	status )

Check the status of a job.

This function is non-blocking and returns immediately with the job status. It is not required to call this function before calling QDMI_device_job_get_results.

Parameters

[in]	job	The job to check the status of. Must not be `NULL`.
[out]	status	The status of the job. Must not be `NULL`.

Returns: QDMI_SUCCESS if the job status was successfully checked.; QDMI_ERROR_INVALIDARGUMENT if job or status is NULL.; QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.; QDMI_ERROR_FATAL if the job status could not be checked.

◆ QDMI_device_job_wait()

int QDMI_device_job_wait ( QDMI_Device_Job job )

Wait for a job to finish.

This function blocks until the job has either finished or has been cancelled.

Parameters

[in] job The job to wait for. Must not be NULL.

Returns: QDMI_SUCCESS if the job is finished or canceled.; QDMI_ERROR_INVALIDARGUMENT if job is NULL.; QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.; QDMI_ERROR_FATAL if the job could not be waited for and this function returns before the job has finished or has been canceled.

◆ QDMI_device_job_get_results()

int QDMI_device_job_get_results	(	QDMI_Device_Job	job,
		QDMI_Job_Result	result,
		size_t	size,
		void *	data,
		size_t *	size_ret )

Retrieve the results of a job.

Parameters

[in]	job	The job to retrieve the results from. Must not be `NULL`.
[in]	result	The result to retrieve. Must be one of the values specified for QDMI_Job_Result.
[in]	size	The size of the buffer pointed to by `data` in bytes. Must be greater or equal to the size of the return type specified for the QDMI_Job_Result `result`, except when `data` is `NULL`, in which case it is ignored.
[out]	data	A pointer to the memory location where the results will be stored. If this is `NULL`, it is ignored.
[out]	size_ret	The actual size of the data being queried in bytes. If this is `NULL`, it is ignored.

Returns

QDMI_SUCCESS if the device supports the specified result and, when data is not NULL, the results were successfully retrieved.

QDMI_ERROR_INVALIDARGUMENT if

job is NULL,
job has not finished,
job was canceled,
result is invalid, or
data is not NULL and size is smaller than the size of the data being queried.

QDMI_ERROR_PERMISSIONDENIED if the device does not allow using the device job interface for the current session.

QDMI_ERROR_FATAL if an error occurred during the retrieval.

Remarks: Calling this function with data set to NULL is expected to allow checking if the device supports the specified result without retrieving the result and without the need to provide a buffer for the result. Additionally, the size of the buffer required to retrieve the result is returned in size_ret if size_ret is not NULL. See the QDMI_job_get_results documentation for an example.

◆ QDMI_device_job_free()

void QDMI_device_job_free ( QDMI_Device_Job job )

Free a job.

Free the resources associated with a job. Using a job handle after it was freed is undefined behavior.

Parameters

[in] job The job to free.

Description

Typedefs

Functions

Typedef Documentation

◆ QDMI_Device_Job

Function Documentation

◆ QDMI_device_session_create_device_job()

◆ QDMI_device_job_set_parameter()

◆ QDMI_device_job_submit()

◆ QDMI_device_job_cancel()

◆ QDMI_device_job_check()

◆ QDMI_device_job_wait()

◆ QDMI_device_job_get_results()

◆ QDMI_device_job_free()