Commonly used when using the QRMI C API
◆ 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
if (last_error != NULL) {
printf("last error = %s\n", 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()
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()
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;
for (int i = 0; i < num_names; i++) {
printf("[%s]\n", names[i]);
}
}
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()
Free a string allocated by C API
Safety
Example
char *target = NULL;
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