ExecutionResult

An ExecutionResult is the struct you receive from a call to either execute_on_qvm or execute_on_qpu. This struct is implemented as a tagged union, describing the possible outcomes of program execution.

SAFETY

You must pass this struct to free_execution_result when you're done with it to avoid leaking the memory.

Any RegisterData which was retrieved from this result will be freed when this is called.

Definition

typedef struct ExecutionResult {
    ExecutionResult_Tag tag;
    union {
        struct {
            struct ExecutionData success;
        };
        struct {
            char *error;
        };
    };
} ExecutionResult;

Variants

There are multiple variants of ExecutionResult. The tag attribute determines which is in use via an enum:

typedef enum ExecutionResult_Tag {
    ExecutionResult_Success,
    ExecutionResult_Error,
} ExecutionResult_Tag;

The Error variant indicates that execution failed. The Success variant is populated in the case of a successful run, and contains an ExecutionData.

Error

If something goes wrong, tag will be ExecutionResult_Error, indicating it is the Error variant. This variant is a human-readable string of the error that occurred.

Error Example

Here, result.error is that string:

    unsigned int shots = 3;
    Executable *exe = executable_from_quil(BELL_STATE_PROGRAM);
    wrap_in_shots(exe, shots);
    ExecutionResult *result = execute_on_qvm(exe);

    if (result->tag == ExecutionResult_Error) {
        return fail(
                TEST_NAME,
                result->error,
                exe,
                result
        );
    }

Success

If there is not an error, tag will instead be ExecutionResult_Success. The success attribute is an ExecutionData.

Handle Example

    const RegisterData *ro = get_data(result->success.handle, "ro");
    if (ro == NULL) {
        return fail(
                TEST_NAME,
                "ro register was not in result",
                exe,
                result
        );
    }