Quantum Resource Management Interface (QRMI) C API
Loading...
Searching...
No Matches
Common

Functions

QrmiReturnCode qrmi_log_callback_set (QrmiLogCallback callback)
QrmiReturnCode qrmi_string_free (char *ptr)
QrmiReturnCode qrmi_string_array_free (size_t size, char *array[])
char * qrmi_get_last_error (void)

Detailed Description

Commonly used when using the QRMI C API

Function Documentation

◆ qrmi_get_last_error()

char * qrmi_get_last_error ( void )

Returns the last error message that occurred during an FFI call from C to Rust. This function is designed to be thread-safe by using thread-local storage, ensuring that each thread retrieves its own error message independently.etrieves the most recent error encountered during API call.

Behavior

  • If an error was previously set in the current thread via set_last_error(), this function returns a pointer to a null-terminated C string (const char*) containing the error message.
  • If no error was set, it returns a null pointer (NULL).
  • After returning the error message, the internal error state is cleared for the current thread. Subsequent calls will return NULL until a new error is set.

Thread Safety

This function uses Rust's thread_local! macro and RefCell to store error messages per thread. This design mirrors the behavior of errno in POSIX and GetLastError() in Windows, ensuring compatibility with multithreaded C environments.

Example

char * last_error = qrmi_get_last_error();
if (last_error != NULL) {
printf("last error = %s\n", last_error);
qrmi_string_free(last_error);
}
char * qrmi_get_last_error(void)
QrmiReturnCode qrmi_string_free(char *ptr)
Returns
message text of the most recent error. The caller takes ownership of the returned string and must release it with qrmi_string_free() once done with it (or it will leak). Returns NULL if no error has been recorded yet.
Version
0.8.0

◆ qrmi_log_callback_set()

QrmiReturnCode qrmi_log_callback_set ( QrmiLogCallback callback)

Registers a QRMI log callback for C hosts.

Once registered, all log records produced by this library (subject to the active RUST_LOG filter, default level warn) are routed to callback instead of stderr.

Pass NULL to clear the current callback and revert to the default stderr writer.

Safety

  • If callback is non-null, it must remain a valid, callable function pointer for as long as it might still be invoked. Because a currently-executing log call may have already captured the previous callback pointer, do not unload code backing a callback immediately after replacing or clearing it — a small number of in-flight calls may still land on the old pointer.

Example

void my_log_cb(const char *level, const char *target, const char *message) {
fprintf(stderr, "[%s] %s: %s\n", level, target, message);
}
QrmiReturnCode qrmi_log_callback_set(QrmiLogCallback callback)
QrmiReturnCode
Definition qrmi.h:55
Parameters
(callback)[in] Callback function, or NULL to clear.
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.20.0

◆ qrmi_string_array_free()

QrmiReturnCode qrmi_string_array_free ( size_t size,
char * array[] )

Free a string array allocated by C API

Safety

  • size and array must be ones returned by the related C API such as qrmi_config_resource_names_get().
  • Specifying an incorrect size value must lead to memory leaks or memory corruption.

Example

size_t num_names = 0;
char **names = NULL;
QrmiReturnCode rc = qrmi_config_resource_names_get(cnf, &num_names, &names);
for (int i = 0; i < num_names; i++) {
printf("[%s]\n", names[i]);
}
qrmi_string_array_free(num_names, names);
}
QrmiReturnCode qrmi_config_resource_names_get(QrmiConfig *config, size_t *num_names, char **names[])
QrmiReturnCode qrmi_string_array_free(size_t size, char *array[])
@ QRMI_RETURN_CODE_SUCCESS
Definition qrmi.h:59
Parameters
(size)[in] number of strings in a string array
(array)[in] a pointer to a string array to be free
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.6.0

◆ qrmi_string_free()

QrmiReturnCode qrmi_string_free ( char * ptr)

Free a string allocated by C API

Safety

Example

char *target = NULL;
rc = qrmi_resource_target(qrmi, &target);
printf("target = %s\n", target);
}
QrmiReturnCode qrmi_resource_target(QrmiQuantumResource *qrmi, char **outp)
Parameters
(ptr)[in] pointer to the memory to be free
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.6.0