QDMI Client Job Interface

Description

Provides functions to manage client-side jobs.

A job is a task submitted by a client 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 client job is as follows:

• Create a job with QDMI_device_create_job.
• Set programs with QDMI_job_set_programs and other parameters with QDMI_job_set_parameter.
• Submit the job to the device with QDMI_job_submit.
• Check the status of the job with QDMI_job_check.
• Wait for the job to finish with QDMI_job_wait.
• Retrieve each program's results with QDMI_job_get_results.
• Free the job with QDMI_job_free when it is no longer used.

Alternatively, a client may retrieve a previously submitted job with QDMI_session_retrieve_job_by_id and continue managing it through the same interface.

Typedefs
typedef struct QDMI_Job_impl_d *	QDMI_Job
	A handle for a client-side job.
typedef enum QDMI_JOB_PARAMETER_T	QDMI_Job_Parameter
	Job parameter type.
typedef enum QDMI_JOB_PROPERTY_T	QDMI_Job_Property
	Job property type.

Enumerations
enum	QDMI_JOB_PARAMETER_T {   QDMI_JOB_PARAMETER_SHOTSNUM = 2 , QDMI_JOB_PARAMETER_MAX = 3 , QDMI_JOB_PARAMETER_CUSTOM1 = 999999995 , QDMI_JOB_PARAMETER_CUSTOM2 = 999999996 ,   QDMI_JOB_PARAMETER_CUSTOM3 = 999999997 , QDMI_JOB_PARAMETER_CUSTOM4 = 999999998 , QDMI_JOB_PARAMETER_CUSTOM5 = 999999999 }
	Enum of the job parameters that can be set. More...
enum	QDMI_JOB_PROPERTY_T {   QDMI_JOB_PROPERTY_ID = 0 , QDMI_JOB_PROPERTY_PROGRAMFORMAT = 1 , QDMI_JOB_PROPERTY_SHOTSNUM = 3 , QDMI_JOB_PROPERTY_QUEUEPOSITION = 4 ,   QDMI_JOB_PROPERTY_PROGRAMSNUM = 5 , QDMI_JOB_PROPERTY_MAX = 6 , QDMI_JOB_PROPERTY_CUSTOM1 = 999999995 , QDMI_JOB_PROPERTY_CUSTOM2 = 999999996 ,   QDMI_JOB_PROPERTY_CUSTOM3 = 999999997 , QDMI_JOB_PROPERTY_CUSTOM4 = 999999998 , QDMI_JOB_PROPERTY_CUSTOM5 = 999999999 }
	Enum of the job properties that can be queried via QDMI_job_query_property as part of the client interface. More...

Functions
int	QDMI_device_create_job (QDMI_Device device, QDMI_Job *job)
	Create a job.
int	QDMI_session_retrieve_job_by_id (QDMI_Device device, const char *job_id, QDMI_Job *job)
	Retrieve an existing job by its ID.
int	QDMI_job_set_parameter (QDMI_Job job, QDMI_Job_Parameter param, size_t size, const void *value)
	Set a parameter for a job.
int	QDMI_job_set_programs (QDMI_Job job, QDMI_Program_Format format, size_t count, const size_t *sizes, const void *const *programs)
	Set one or more programs for a job.
int	QDMI_job_get_program (QDMI_Job job, size_t program_index, size_t size, void *data, size_t *size_ret)
	Retrieve one program in input order.
int	QDMI_job_get_program_status (QDMI_Job job, size_t program_index, QDMI_Job_Status *status)
	Query the current status of one program in a job.
int	QDMI_job_query_property (QDMI_Job job, QDMI_Job_Property prop, size_t size, void *value, size_t *size_ret)
	Query a job property.
int	QDMI_job_submit (QDMI_Job job)
	Submit a job to the device.
int	QDMI_job_cancel (QDMI_Job job)
	Cancel an already submitted job.
int	QDMI_job_check (QDMI_Job job, QDMI_Job_Status *status)
	Check the status of a job.
int	QDMI_job_wait (QDMI_Job job, size_t timeout)
	Wait for a job to finish.
int	QDMI_job_get_results (QDMI_Job job, size_t program_index, QDMI_Job_Result result, size_t size, void *data, size_t *size_ret)
	Retrieve one program's results from a job.
void	QDMI_job_free (QDMI_Job job)
	Free a job.

Typedef Documentation

QDMI_Job

typedef struct QDMI_Job_impl_d* QDMI_Job

A handle for a client-side job.

An opaque pointer to a type defined by the driver that encapsulates all information about a job submitted to a device by a client. The job belongs to the session that supplied its device handle. The client must free the job before it frees that session.

Remarks

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

See also

QDMI_Device_Job for the device-side job handle.

Enumeration Type Documentation

QDMI_JOB_PARAMETER_T

enum QDMI_JOB_PARAMETER_T

Enum of the job parameters that can be set.

If not noted otherwise, parameters are optional and drivers must not require them to be set.

Enumerator
QDMI_JOB_PARAMETER_SHOTSNUM	2	size_t The number of shots to execute for each program in a job. Value 0 is reserved for the removed program format parameter. Value 1 is reserved for the removed program parameter; do not reuse it. If this parameter is not set, a device-specific default is used.
QDMI_JOB_PARAMETER_MAX	3	The maximum value of the enum. It can be used by drivers for bounds checking and validation of function parameters. Attention This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.
QDMI_JOB_PARAMETER_CUSTOM1	999999995	This enum value is reserved for a custom parameter. The driver defines the meaning and the type of this parameter. Attention The value of this enum member must not be changed to maintain binary compatibility.
QDMI_JOB_PARAMETER_CUSTOM2	999999996	See also QDMI_JOB_PARAMETER_CUSTOM1
QDMI_JOB_PARAMETER_CUSTOM3	999999997	See also QDMI_JOB_PARAMETER_CUSTOM1
QDMI_JOB_PARAMETER_CUSTOM4	999999998	See also QDMI_JOB_PARAMETER_CUSTOM1
QDMI_JOB_PARAMETER_CUSTOM5	999999999	See also QDMI_JOB_PARAMETER_CUSTOM1

QDMI_JOB_PROPERTY_T

enum QDMI_JOB_PROPERTY_T

Enum of the job properties that can be queried via QDMI_job_query_property as part of the client interface.

In particular, every parameter's value that can be set via QDMI_job_set_parameter can be queried.

Enumerator
QDMI_JOB_PROPERTY_ID	0	char* (string) The job's ID. The ID must uniquely identify a job for the specific driver. It may be used with QDMI_session_retrieve_job_by_id to obtain a new QDMI_Job handle for an existing remote job. It may, for example, correspond to the job ID provided by the QDMI device implementation via QDMI_device_job_query_property as part of the device interface or may be generated by the driver.
QDMI_JOB_PROPERTY_PROGRAMFORMAT	1	QDMI_Program_Format The format of the program to be executed. A query returns QDMI_ERROR_BADSTATE until a format is set, or QDMI_ERROR_NOTSUPPORTED if a retrieved job has no format metadata. This property returns the format set through QDMI_job_set_programs.
QDMI_JOB_PROPERTY_SHOTSNUM	3	Value 2 is reserved for the removed program property; do not reuse it. size_t The number of shots to execute for each program in a job. Note This property returns the value of the QDMI_JOB_PARAMETER_SHOTSNUM parameter.
QDMI_JOB_PROPERTY_QUEUEPOSITION	4	size_t The current number of jobs ahead of this job in its queue. Querying this property must refresh the job's status and queue position. The property can only be queried while the refreshed status is QDMI_JOB_STATUS_QUEUED; otherwise, the query must return QDMI_ERROR_BADSTATE. If the provider only exposes a lower bound, the implementation reports that lower bound. For example, a provider value of >50 is reported as 50. The property may yield QDMI_ERROR_NOTSUPPORTED if the implementation cannot obtain a trustworthy queue position.
QDMI_JOB_PROPERTY_PROGRAMSNUM	5	size_t The number of programs in the job. A single-program job reports one. A job has no program count until its program payload has been set; a query before that returns QDMI_ERROR_BADSTATE. The count remains stable after submission.
QDMI_JOB_PROPERTY_MAX	6	The maximum value of the enum. It can be used by devices for bounds checking and validation of function parameters. Attention This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.
QDMI_JOB_PROPERTY_CUSTOM1	999999995	This enum value is reserved for a custom parameter. The driver defines the meaning and the type of this parameter. Attention The value of this enum member must not be changed to maintain binary compatibility.
QDMI_JOB_PROPERTY_CUSTOM2	999999996	See also QDMI_JOB_PROPERTY_CUSTOM1
QDMI_JOB_PROPERTY_CUSTOM3	999999997	See also QDMI_JOB_PROPERTY_CUSTOM1
QDMI_JOB_PROPERTY_CUSTOM4	999999998	See also QDMI_JOB_PROPERTY_CUSTOM1
QDMI_JOB_PROPERTY_CUSTOM5	999999999	See also QDMI_JOB_PROPERTY_CUSTOM1

Function Documentation

QDMI_device_create_job()

int QDMI_device_create_job	(	QDMI_Device	device,
		QDMI_Job *	job )

Create a job.

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

Parameters

[in]	device	The device 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_job_free when it is no longer used.

Returns

QDMI_SUCCESS if the job was successfully created.

QDMI_ERROR_INVALIDARGUMENT if device or job are NULL.

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

QDMI_ERROR_OUTOFMEM if the driver cannot allocate the job.

QDMI_ERROR_FATAL if job creation failed due to a fatal error.

QDMI_session_retrieve_job_by_id()

int QDMI_session_retrieve_job_by_id	(	QDMI_Device	device,
		const char *	job_id,
		QDMI_Job *	job )

Retrieve an existing job by its ID.

Creates a new local job handle for the existing remote job identified by job_id. Retrieving a job does not submit, clone, or otherwise modify the remote job. The returned handle can be used to query properties, check or wait for completion, cancel the job, and retrieve results.

The job is accessed with the credentials and configuration of the current session. The job ID is an identifier, not an authentication credential. Parameters cannot be set on a retrieved job, and a retrieved job cannot be submitted again. The driver must reconstruct the program count and input-to-result mapping. If historical input metadata is unavailable, queries for the original format or program bytes may return QDMI_ERROR_NOTSUPPORTED without preventing retrieval.

Parameters

[in]	device	The device from which to retrieve the job. Must not be NULL.
[in]	job_id	The nonempty, null-terminated ID returned by QDMI_JOB_PROPERTY_ID. Must not be NULL.
[out]	job	A pointer to a handle that will store the retrieved job. Must not be NULL. The handle must be freed by calling QDMI_job_free when it is no longer used.

Returns

QDMI_SUCCESS if the job was successfully retrieved.

QDMI_ERROR_INVALIDARGUMENT if device, job_id, or job is NULL, or if job_id is empty.

QDMI_ERROR_NOTSUPPORTED if the driver or device does not support retrieving existing jobs or cannot reconstruct the program count and result-index mapping.

QDMI_ERROR_NOTFOUND if no accessible job with job_id exists.

QDMI_ERROR_PERMISSIONDENIED if the current session is not permitted to access the job.

QDMI_ERROR_FATAL if retrieving the job failed due to a fatal error.

QDMI_job_set_parameter()

int QDMI_job_set_parameter	(	QDMI_Job	job,
		QDMI_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_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 driver supports the specified QDMI_Job_Parameter param and, when value is not NULL, the parameter was successfully set.

QDMI_ERROR_NOTSUPPORTED if the driver 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_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_OUTOFMEM if a parameter value cannot be copied.

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

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

Note

By calling this function with value set to NULL, the function can be used to check if the driver supports the specified parameter without setting the parameter and without the need to provide a value.

For example, to check whether the device supports setting the number of shots for a quantum circuit job, the following code pattern can be used:

// Check if the device supports setting the number of shots.
auto ret = QDMI_job_set_parameter(
  job, QDMI_JOB_PARAMETER_SHOTSNUM, 0, nullptr);
if (ret == QDMI_ERROR_NOTSUPPORTED) {
  // The device does not support setting the number of shots.
  ...
}
 
// Set the number of shots.
size_t shots = 8192;
QDMI_job_set_parameter(
  job, QDMI_JOB_PARAMETER_SHOTSNUM, sizeof(size_t), &shots);

QDMI_job_set_programs()

int QDMI_job_set_programs	(	QDMI_Job	job,
		QDMI_Program_Format	format,
		size_t	count,
		const size_t *	sizes,
		const void *const *	programs )

Set one or more programs for a job.

All programs use the same format and the same job parameters, including the shot count. On success, the driver replaces the complete program list with a deep copy of sizes and the program bytes. If validation or copying fails, the existing program list remains unchanged. A driver may convert the programs to a format supported by the device. A driver may use separate underlying jobs only if it preserves the single aggregate ID, lifecycle, cancellation, and retrieval contract. A driver that accepts a list must report its size through QDMI_JOB_PROPERTY_PROGRAMSNUM and expose each result through QDMI_job_get_results. A result's index equals its input program's index; execution order is unspecified. The list has one ID, status, wait operation, and cancellation operation. The job reaches QDMI_JOB_STATUS_DONE only after all programs succeed. Failed or canceled jobs become terminal only after all programs have stopped. Optional per-program outcomes are available through QDMI_job_get_program_status; results of successful programs remain accessible when other programs fail or are canceled.

Parameters

[in]	job	A handle to the job. Must not be NULL.
[in]	format	The exact format of every program. Must be a valid QDMI_Program_Format, including for a single program.
[in]	count	The number of programs. Must be greater than zero. A support check succeeds only if the driver supports this exact cardinality with the configured job parameters.
[in]	sizes	An array of count program sizes in bytes. Must not be NULL and each size must be greater than zero when programs is not NULL. A text program contains exactly one '\0' as its final byte. Binary programs are arbitrary nonempty byte sequences. When programs is NULL, sizes is ignored.
[in]	programs	An array of count program pointers. When the array is not NULL, each pointer must not be NULL. The driver copies all input data before returning. If the array is NULL, the function checks support for the format and cardinality without changing the job.

Returns

QDMI_SUCCESS if the driver supports the count in format and, when programs is not NULL, set the complete list.

QDMI_ERROR_INVALIDARGUMENT if

• job is NULL, count is zero, or format is not valid, or
• the driver supports program lists, programs is not NULL, and sizes is NULL, an element of programs is NULL, an element of sizes is zero, or a text program does not contain exactly one trailing '\0'.

QDMI_ERROR_NOTSUPPORTED if the arguments are valid but the driver cannot accept the format, count, or programs with the configured job parameters. Reserved numeric values of removed formats also return QDMI_ERROR_NOTSUPPORTED.

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

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

QDMI_ERROR_OUTOFMEM if the driver cannot copy the program list.

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

QDMI_job_get_program()

int QDMI_job_get_program	(	QDMI_Job	job,
		size_t	program_index,
		size_t	size,
		void *	data,
		size_t *	size_ret )

Retrieve one program in input order.

The returned bytes include the terminating NUL for text formats. A retrieved job may return QDMI_ERROR_NOTSUPPORTED when its original program bytes are unavailable. The program count is reported by QDMI_JOB_PROPERTY_PROGRAMSNUM.

Parameters

[in]	job	The job to query. Must not be NULL.
[in]	program_index	The zero-based program index.
[in]	size	The size of data in bytes. Ignored if data is NULL.
[out]	data	The buffer for the program bytes, or NULL for a size query.
[out]	size_ret	The required buffer size, or NULL.

Returns

QDMI_SUCCESS if the program bytes were copied, or their size was returned when data is NULL.

QDMI_ERROR_NOTSUPPORTED if the original program is unavailable.

QDMI_ERROR_BADSTATE if no program list has been set.

QDMI_ERROR_OUTOFRANGE if program_index is out of range.

QDMI_ERROR_INVALIDARGUMENT if job is NULL or data is non-NULL and size is too small.

QDMI_ERROR_PERMISSIONDENIED if the session cannot access jobs.

QDMI_ERROR_FATAL if an unexpected error occurred.

QDMI_job_get_program_status()

int QDMI_job_get_program_status	(	QDMI_Job	job,
		size_t	program_index,
		QDMI_Job_Status *	status )

Query the current status of one program in a job.

Individual outcomes are optional. Once reached, a program's terminal status cannot change. An out-of-range index returns QDMI_ERROR_OUTOFRANGE even if individual outcomes are unsupported; results of successful programs remain available when siblings fail or are canceled. A temporary retrieval failure is an error, not QDMI_ERROR_NOTSUPPORTED.

Parameters

[in]	job	The job to query. Must not be NULL.
[in]	program_index	The zero-based input program index.
[out]	status	The program status. Must not be NULL.

Returns

QDMI_SUCCESS if the status was retrieved.

QDMI_ERROR_NOTSUPPORTED if individual outcomes are unavailable.

QDMI_ERROR_BADSTATE if no program list has been set or supported outcomes are not yet ready.

QDMI_ERROR_OUTOFRANGE if program_index is out of range.

QDMI_ERROR_INVALIDARGUMENT if job or status is NULL.

QDMI_ERROR_FATAL if an unexpected error occurred.

QDMI_job_query_property()

int QDMI_job_query_property	(	QDMI_Job	job,
		QDMI_Job_Property	prop,
		size_t	size,
		void *	value,
		size_t *	size_ret )

Query a job property.

Parameters

[in]	job	A handle to a job for which to query prop. Must not be NULL.
[in]	prop	The property to query. Must be one of the values specified for QDMI_Job_Property.
[in]	size	The size of the memory pointed to by value in bytes. Must be greater or equal to the size of the return type specified for prop, except when value is NULL, in which case it is ignored.
[out]	value	A pointer to the memory location where the value of the property 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 job supports the specified property and, when value is not NULL, the property was successfully retrieved.

QDMI_ERROR_NOTSUPPORTED if the job does not support the property.

QDMI_ERROR_INVALIDARGUMENT if

• job is NULL,
• prop is invalid, or
• value is not NULL and size is less than the size of the data being queried.

QDMI_ERROR_BADSTATE if the property cannot be queried in the current state of the job, for example, because the job failed or the property is not initialized because it has no default value and was not set.

QDMI_ERROR_FATAL if an unexpected error occurred.

Note

By calling this function with value set to NULL, the function can be used to check if the job supports the specified property without retrieving the property and without the need to provide a buffer for it. Additionally, the size of the buffer needed to retrieve the property is returned in size_ret if size_ret is not NULL.

For example, to query the id of a job, the following code pattern can be used:

// Query the size of the property.
size_t size;
QDMI_job_query_property(
  job, QDMI_JOB_PROPERTY_ID, 0, nullptr, &size);
 
// Allocate memory for the property.
auto id = std::string(size - 1, '\0');
 
// Query the property.
QDMI_job_query_property(
  job, QDMI_JOB_PROPERTY_NAME, size, name.data(), nullptr);

QDMI_job_submit()

int QDMI_job_submit

(

QDMI_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_job_check and QDMI_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_BADSTATE if a required program or format is missing or the job was retrieved.

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

QDMI_ERROR_FATAL if the job submission failed.

QDMI_job_cancel()

int QDMI_job_cancel

(

QDMI_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 driver does not allow using the client job interface for the device in the current session.

QDMI_ERROR_FATAL if the job could not be canceled.

QDMI_job_check()

int QDMI_job_check	(	QDMI_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_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 driver does not allow using the client job interface for the device in the current session.

QDMI_ERROR_FATAL if the job status could not be checked.

QDMI_job_wait()

int QDMI_job_wait	(	QDMI_Job	job,
		size_t	timeout )

Wait for a job to finish.

This function blocks until the job reaches QDMI_JOB_STATUS_DONE, QDMI_JOB_STATUS_CANCELED, or QDMI_JOB_STATUS_FAILED, or until the timeout is reached. Call QDMI_job_check after a successful wait to distinguish terminal states. If timeout is not zero, this function returns latest after the specified number of seconds.

Parameters

[in]	job	The job to wait for. Must not be NULL.
[in]	timeout	The timeout in seconds. If this is zero, the function waits indefinitely for a terminal state.

Returns

QDMI_SUCCESS if the job reached any terminal state.

QDMI_ERROR_INVALIDARGUMENT if job is NULL.

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

QDMI_ERROR_TIMEOUT if timeout is not zero and the job did not reach a terminal state within the specified time.

QDMI_ERROR_FATAL if the job could not be waited for and this function returns before the job reached a terminal state.

QDMI_job_get_results()

int QDMI_job_get_results	(	QDMI_Job	job,
		size_t	program_index,
		QDMI_Job_Result	result,
		size_t	size,
		void *	data,
		size_t *	size_ret )

Retrieve one program's results from a job.

Results are available when the selected program has succeeded, even if other programs are still running, failed, or canceled. Devices exposing only aggregate outcomes provide results after the job reaches QDMI_JOB_STATUS_DONE.

Parameters

[in]	job	The job to retrieve the results from. Must not be NULL.
[in]	program_index	The zero-based program index. Must be less than QDMI_JOB_PROPERTY_PROGRAMSNUM.
[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 than or equal to the size of the requested result, except when data is NULL, in which case it is ignored.
[out]	data	The buffer in which to store the result. If this is NULL, it is ignored.
[out]	size_ret	The required buffer size 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, retrieved it successfully.

QDMI_ERROR_NOTSUPPORTED if the device does not support the specified result.

QDMI_ERROR_BADSTATE if the selected program has not succeeded.

QDMI_ERROR_OUTOFRANGE if program_index is greater than or equal to the number of programs in the job.

QDMI_ERROR_INVALIDARGUMENT if

• job is NULL,
• result is invalid, or
• data is not NULL and size is too small.

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

QDMI_ERROR_FATAL if an error occurred during retrieval.

Note

Calling this function with data set to NULL checks support and returns the required buffer size in size_ret when it is not NULL.

For example, to query the first program's measurement results:

size_t size;
auto ret = QDMI_job_get_results(
  job, 0, QDMI_JOB_RESULT_SHOTS, 0, nullptr, &size);
std::string shots(size, '\0');
QDMI_job_get_results(
  job, 0, QDMI_JOB_RESULT_SHOTS, size, shots.data(), nullptr);
shots.pop_back();

QDMI_job_free()

void QDMI_job_free

(

QDMI_Job

job

)

Free a job.

Free the resources associated with a job. Using a job handle after it has been freed is undefined behavior. Freeing a job handle does not necessarily cancel or delete the underlying job; this behavior is device-specific.

Parameters

[in]

job

The job to free.