Error types for cross-.so error reporting. More...
Go to the source code of this file.
Typedefs | |
| typedef struct entropic_engine * | entropic_handle_t |
| Opaque handle to an entropic engine instance. | |
| typedef void(* | entropic_error_callback_t) (entropic_error_t code, const char *message, void *user_data) |
| Error callback type for async error reporting. | |
Functions | |
| ENTROPIC_EXPORT const char * | entropic_last_error (entropic_handle_t handle) |
| Get the last error message for a handle. | |
| ENTROPIC_EXPORT const char * | entropic_error_name (entropic_error_t code) |
| Get the human-readable name for an error code. | |
| ENTROPIC_EXPORT entropic_error_t | entropic_set_error_callback (entropic_handle_t handle, entropic_error_callback_t callback, void *user_data) |
| Register an error callback on a handle. | |
Detailed Description
Error types for cross-.so error reporting.
Exceptions do NOT cross .so boundaries. All cross-boundary error reporting uses:
- Return codes — C API functions return entropic_error_t.
- Error callbacks — consumer registers for async errors.
- Error state on handles — entropic_last_error() returns last message.
- Thread safety
- entropic_last_error() is per-handle, not global. Each handle maintains its own error state. Thread-safe for different handles; concurrent access to the SAME handle requires external synchronization.
- Version
- 1.8.0
Definition in file error.h.
Typedef Documentation
◆ entropic_error_callback_t
| typedef void(* entropic_error_callback_t) (entropic_error_t code, const char *message, void *user_data) |
Error callback type for async error reporting.
Registered via entropic_set_error_callback(). Called from the thread where the error occurs. The callback MUST NOT call back into the entropic API (deadlock risk). Keep callbacks short — log and return.
- Parameters
-
code Error code. message Null-terminated error message. Valid only for callback duration. user_data Opaque pointer passed during registration. @callback
- Version
- 1.8.0
◆ entropic_handle_t
| typedef struct entropic_engine* entropic_handle_t |
Opaque handle to an entropic engine instance.
All per-handle functions (including entropic_last_error) operate on this. Created by entropic_create(), destroyed by entropic_destroy().
Enumeration Type Documentation
◆ entropic_error_t
| enum entropic_error_t |
Error codes returned by all C API functions.
ENTROPIC_OK (0) on success. All other values indicate failure. Use entropic_error_name() to get a human-readable string for logging.
Function Documentation
◆ entropic_error_name()
| ENTROPIC_EXPORT const char * entropic_error_name | ( | entropic_error_t | code | ) |
Get the human-readable name for an error code.
- Parameters
-
code Error code.
- Returns
- Static string like "ENTROPIC_ERROR_LOAD_FAILED". Never NULL.
- Example
- entropic_error_t err = entropic_configure(h, cfg);if (err != ENTROPIC_OK) {spdlog::error("configure failed: {} — {}",entropic_error_name(err), entropic_last_error(h));}ENTROPIC_EXPORT entropic_error_t entropic_configure(entropic_handle_t handle, const char *config_json)Configure the engine from a JSON config string.Definition entropic.cpp:1526ENTROPIC_EXPORT const char * entropic_error_name(entropic_error_t code)Get the human-readable name for an error code.Definition error.cpp:84ENTROPIC_EXPORT const char * entropic_last_error(entropic_handle_t handle)Get the last error message for a handle.Definition entropic.cpp:90
- Version
- 1.8.0
- Parameters
-
code Error code to look up.
- Returns
- Static string naming the error code. Never NULL.
- Version
- 1.8.0 @utility
◆ entropic_last_error()
| ENTROPIC_EXPORT const char * entropic_last_error | ( | entropic_handle_t | handle | ) |
Get the last error message for a handle.
Returns the error message from the most recent failed operation on this handle. The returned string is owned by the handle and valid until the next API call on the same handle.
- Parameters
-
handle Engine handle (may be NULL for global errors during create).
- Returns
- Null-terminated error message string, or "" if no error. Owned by the handle — do NOT free.
- Version
- 1.8.0
Get the last error message for a handle.
Pre-v2.2.6 the public symbol lived in src/types/error.cpp and ignored its handle parameter (v1.8.0 TODO never done). Moved here because the private engine_handle struct is only visible in the facade. Returns a thread-local cache copy so the pointer stays valid until the same thread reads again — matches the v1.8.0 contract documented in include/entropic/types/error.h.
@utility
- Version
- 2.2.6
Definition at line 90 of file entropic.cpp.
◆ entropic_set_error_callback()
| ENTROPIC_EXPORT entropic_error_t entropic_set_error_callback | ( | entropic_handle_t | handle, |
| entropic_error_callback_t | callback, | ||
| void * | user_data | ||
| ) |
Register an error callback on a handle.
Only one callback per handle. Setting a new one replaces the previous. Pass NULL to remove.
- Parameters
-
handle Engine handle. callback Callback function, or NULL to remove. user_data Opaque pointer forwarded to callback.
- Returns
- ENTROPIC_OK on success, ENTROPIC_ERROR_INVALID_ARGUMENT if handle is NULL.
- Version
- 1.8.0
- Parameters
-
handle Engine handle. callback Callback function, or NULL to remove. user_data Opaque pointer forwarded to callback.
- Returns
- ENTROPIC_OK on success, ENTROPIC_ERROR_INVALID_ARGUMENT if handle is NULL.
- Version
- 1.8.0
