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.

The typical workflow for a client job is as follows:

• Create a job with QDMI_device_create_job.
• Set one program and other parameters with QDMI_job_set_parameter, or set a program list with QDMI_job_set_programs.
• 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_PROGRAMFORMAT = 0 , QDMI_JOB_PARAMETER_SHOTSNUM = 1 , QDMI_JOB_PARAMETER_MAX = 2 , QDMI_JOB_PARAMETER_CUSTOM1 = QDMI_CUSTOM_ENUM_VALUE_MIN ,   QDMI_JOB_PARAMETER_CUSTOM2 = 999999996 , QDMI_JOB_PARAMETER_CUSTOM3 = 999999997 , QDMI_JOB_PARAMETER_CUSTOM4 = 999999998 , QDMI_JOB_PARAMETER_CUSTOM5 = 999999999 ,   QDMI_JOB_PARAMETER_CUSTOM_MAX = QDMI_CUSTOM_ENUM_VALUE_MAX }
	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_PROGRAM = 2 , QDMI_JOB_PROPERTY_SHOTSNUM = 3 ,   QDMI_JOB_PROPERTY_QUEUEPOSITION = 4 , QDMI_JOB_PROPERTY_PROGRAMSNUM = 5 , QDMI_JOB_PROPERTY_MAX = 6 , QDMI_JOB_PROPERTY_CUSTOM1 = QDMI_CUSTOM_ENUM_VALUE_MIN ,   QDMI_JOB_PROPERTY_CUSTOM2 = 999999996 , QDMI_JOB_PROPERTY_CUSTOM3 = 999999997 , QDMI_JOB_PROPERTY_CUSTOM4 = 999999998 , QDMI_JOB_PROPERTY_CUSTOM5 = 999999999 ,   QDMI_JOB_PROPERTY_CUSTOM_MAX = QDMI_CUSTOM_ENUM_VALUE_MAX }
	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, const 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_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.

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_PROGRAMFORMAT	0	QDMI_Program_Format The format of the program to be executed. This parameter is required. If the device does not support the specified program format, it is up to the driver to decide whether to return QDMI_ERROR_NOTSUPPORTED from QDMI_job_set_parameter or to convert the program to a supported format. A translating driver retains the client-submitted descriptor so that properties and retrieved jobs report the client value rather than the executed device value. Setting the same exact descriptor keeps an existing program payload. Setting a different supported descriptor clears the payload. Every error leaves the descriptor and payload unchanged.
QDMI_JOB_PARAMETER_SHOTSNUM	1	size_t The number of shots to execute for a quantum circuit job. If this parameter is not set, a device-specific default is used.
QDMI_JOB_PARAMETER_MAX	2	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	QDMI_CUSTOM_ENUM_VALUE_MIN	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_PARAMETER_CUSTOM_MAX	QDMI_CUSTOM_ENUM_VALUE_MAX	The largest syntactically valid custom value.

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. This property returns the format set through QDMI_JOB_PARAMETER_PROGRAMFORMAT or QDMI_job_set_programs. Note This property returns the exact client-submitted value of QDMI_JOB_PARAMETER_PROGRAMFORMAT, including on a translated or retrieved job. The executed device descriptor can differ.
QDMI_JOB_PROPERTY_PROGRAM	2	void* The program to be executed. Note This property returns the program set through QDMI_job_set_programs when the job contains one program. A query for a multi-program job returns QDMI_ERROR_NOTSUPPORTED.
QDMI_JOB_PROPERTY_SHOTSNUM	3	size_t The number of shots to execute for a quantum circuit 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	QDMI_CUSTOM_ENUM_VALUE_MIN	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
QDMI_JOB_PROPERTY_CUSTOM_MAX	QDMI_CUSTOM_ENUM_VALUE_MAX	The largest syntactically valid custom value.

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_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. Retrieval is all-or-nothing: the driver must reconstruct the exact historical format descriptor, program count, status, and mapping from each input index to its results. This also applies when the historical descriptor is no longer advertised. The driver must return QDMI_ERROR_NOTSUPPORTED if it cannot reconstruct all of this information.

A translating driver must restore the exact client-submitted descriptor and its mapping to the executed descriptor. The client descriptor may no longer appear in the device's current supported-format list. A driver that cannot reconstruct this information losslessly returns QDMI_ERROR_NOTSUPPORTED.

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 all required job metadata and result-index mappings.

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 program 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,
		const 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 exact format descriptor and the same job parameters, including the shot count. On success, the driver replaces the complete program list with a deep copy of format, 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. One program failure sets the aggregate status to QDMI_JOB_STATUS_FAILED. Cancellation sets it to QDMI_JOB_STATUS_CANCELED. Results are available only for a job with status QDMI_JOB_STATUS_DONE; QDMI exposes no partial results.

Parameters

[in]	job	A handle to the job. Must not be NULL.
[in]	format	The exact format of every program. Must point to a valid QDMI_Program_Format when the driver supports program lists. It must not be NULL, including for a support check.
[in]	count	The number of programs. Must be greater than zero. A support check succeeds only if the driver supports this exact cardinality.
[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 NUL, 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. Each pointer must not be NULL. The driver copies all input data before returning. If this is NULL, the function checks support for the exact descriptor and cardinality and does not change the job.

Returns

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

QDMI_ERROR_INVALIDARGUMENT if

• job or format is NULL, or count is zero,
• the driver supports program lists and format is not a valid descriptor, 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 NUL.

QDMI_ERROR_NOTSUPPORTED if the arguments are valid but the driver cannot accept program lists, format, or one of the programs.

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_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.

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_OUTOFRANGE if program_index is greater than or equal to the number of programs in the job.

QDMI_ERROR_INVALIDARGUMENT if

• job is NULL,
• job does not have status QDMI_JOB_STATUS_DONE,
• 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.