SarasasChipWorkshop/sarasacw-omrf
1
0
Fork 0
Code Activity

feat: improve last_error and cffi_wrapper

Browse Source
This commit is contained in:
yyc12345
2026-07-30 15:08:46 +08:00
parent 708e16a222
commit f84e1a5d9c
5 changed files with 555 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files
omrf/src/cffi.rs
+157
View File
@@ -0,0 +1,157 @@
//! Ergonomic helpers for authoring `extern "C"` functions.
//!
//! Contains the following macros:
//!
//! - `in_param_ty!` / `out_param_ty!` -- annotate the direction (in / out) of an FFI parameter.
//! - `deref_out_param!` / `set_out_param!` -- write values through output parameter pointers.
//! - `cffi_wrapper!` -- wrap a `Result`-returning inner function into the C-style outcome pattern
//! (an [`CError`](crate::last_error::CError) return value), backed by
//! [`last_error`](crate::last_error) for outcome/message storage.
/// Annotate a parameter as an input parameter (passed by value). Expands to the type unchanged.
#[macro_export]
macro_rules! in_param_ty {
($t:ty) => {
$t
};
}
/// Annotate a parameter as an output parameter. Expands to `*mut T` -- a mutable raw pointer the
/// callee writes the result through.
#[macro_export]
macro_rules! out_param_ty {
($t:ty) => {
*mut $t
};
}
/// Expand to a place expression that writes through an output parameter pointer (`*ptr`).
///
/// Intended for the left-hand side of an assignment within an `unsafe` block. Composing several of
/// these into a tuple enables structured destructuring assignment for multiple outputs, e.g.
/// `unsafe { (deref_out_param!(a), deref_out_param!(b)) = (x, y) };` expands to
/// `unsafe { (*a, *b) = (x, y) };`.
#[macro_export]
macro_rules! deref_out_param {
($lhs:expr) => {
*$lhs
};
}
/// Write a single value through an output parameter pointer.
///
/// Convenience wrapper around [`deref_out_param!`] for the common single-output case; expands to
/// `unsafe { deref_out_param!($lhs) = $rhs };`.
#[macro_export]
macro_rules! set_out_param {
($lhs:expr, $rhs:expr) => {
unsafe {
$crate::deref_out_param!($lhs) = $rhs;
}
};
}
/// Wrap an inner `Result`-returning function body into a C-style outcome.
///
/// The four accepted shapes are:
///
/// - no input, no output: `cffi_wrapper!(|| { ... })`
/// - inputs, no output: `cffi_wrapper!(|p1: T1, p2: T2| { ... })`
/// - no input, outputs: `cffi_wrapper!(|| -> (o1: O1, o2: O2) { ... })`
/// - inputs and outputs: `cffi_wrapper!(|p1: T1| -> (o1: O1, o2: O2, o3: O3) { ... })`
///
/// The output list accepts any number of outputs (one or more). The inner function must return
/// `Result<O>` for a single output or `Result<(O1, O2, ...)>` for multiple outputs; the wrapper
/// writes each value to its corresponding output parameter via structured destructuring assignment
/// through the pointers. On error no output parameter is written.
///
/// The identifiers used for inputs and outputs must match the surrounding function's parameter
/// names, since the expansion forwards them directly.
///
/// # Required environment conventions
///
/// This macro expands in the caller's scope and internally relies on
/// [`last_error`](crate::last_error), so the following names must be in scope there:
///
/// - `Result<T>` -- a type alias for `core::result::Result<T, UserError>`.
/// - `UserError` -- the project's error type, which must implement [`Display`] and
/// `From<UserError> for `[`CError`](crate::last_error::CError)` so it can be handed to
/// [`set_last_error`](crate::last_error::set_last_error).
///
/// On success the wrapper clears the thread-local last error and yields
/// [`CERROR_OK`](crate::last_error::CERROR_OK) (absolute success); on error it records the
/// error (message via [`Display`], code via the user's `From<UserError> for CError`) and yields the
/// recorded code. Both branches obtain their final value from
/// [`get_error_code`](crate::last_error::get_error_code).
#[macro_export]
macro_rules! cffi_wrapper {
// inputs + one or more outputs
(|$($p:ident: $t:ty),+| -> ($($o:ident: $ot:ty),+) $inner_body:block) => {{
fn inner($($p: $t),+) -> Result<($($ot),+)> $inner_body
match inner($($p),+) {
Ok(rv) => {
unsafe {
($($crate::deref_out_param!($o)),+) = rv;
}
$crate::last_error::clear_last_error();
$crate::last_error::get_error_code()
}
Err(e) => {
$crate::last_error::set_last_error(e);
$crate::last_error::get_error_code()
}
}
}};
// no inputs + one or more outputs
(|| -> ($($o:ident: $ot:ty),+) $inner_body:block) => {{
fn inner() -> Result<($($ot),+)> $inner_body
match inner() {
Ok(rv) => {
unsafe {
($($crate::deref_out_param!($o)),+) = rv;
}
$crate::last_error::clear_last_error();
$crate::last_error::get_error_code()
}
Err(e) => {
$crate::last_error::set_last_error(e);
$crate::last_error::get_error_code()
}
}
}};
// inputs + no outputs
(|$($p:ident: $t:ty),+| $inner_body:block) => {{
fn inner($($p: $t),+) -> Result<()> $inner_body
match inner($($p),+) {
Ok(_) => {
$crate::last_error::clear_last_error();
$crate::last_error::get_error_code()
}
Err(e) => {
$crate::last_error::set_last_error(e);
$crate::last_error::get_error_code()
}
}
}};
// no inputs + no outputs
(|| $inner_body:block) => {{
fn inner() -> Result<()> $inner_body
match inner() {
Ok(_) => {
$crate::last_error::clear_last_error();
$crate::last_error::get_error_code()
}
Err(e) => {
$crate::last_error::set_last_error(e);
$crate::last_error::get_error_code()
}
}
}};
}
omrf/src/last_error.rs
+123 -29
View File
@@ -1,58 +1,152 @@
//! When calling function with dynamic library,
//! function return value indicates whether function has been successfully executed.
//! When function return `false`, programmer may want to know which error occurs.
//!
//! This module provide **thread independent** error message string storage,
//! which is more like Win32 `GetLastError()` but return error message instead of error code.
//! These module provided functions will be called when executing main module functions.
//! Thread-local storage for the outcome of the most recent FFI call on this thread -- both its
//! error *code* and its human-readable *message*.
//!
//! This is closer in spirit to Win32 `FormatMessage` or SQLite's `sqlite3_errmsg` than to
//! `GetLastError`: the conventional pattern is for the FFI function to *return* the code as its
//! return value (see [`get_error_code`]) while this module retains the matching message text for
//! later retrieval (see [`get_error_message`]). The code is also retained here so it can be
//! queried independently of the return value.
//!
//! # Call order
//!
//! The expected usage at each FFI function entry is:
//!
//! 1. Call [`clear_last_error`] to reset the thread state to absolute success (code = `None`,
//! empty message). **This must be done at the entry of every FFI function**; the default state
//! is "absolute success".
//! 2. On failure, call [`set_last_error`] with the error value; this records the code (via
//! `Into<CError>`) and derives the message (via `Display`).
//! 3. The FFI function returns [`get_error_code`] (absolute success if nothing was set, otherwise
//! the recorded code). The foreign side may call [`get_error_message`] for the text.
//!
//! The `cffi_wrapper!` macro automates this whole sequence.
//!
//! # The error code type
//!
//! [`CError`] is defined here as a plain `u32`. [`CERROR_OK`] is the single value that represents
//! absolute, unambiguous success. Every other value's meaning is decided by the consuming project
//! through `From<UserError> for CError`: it may denote a failure, or, like some Win32 functions, a
//! *partial success*.
//!
//! # Migrating from a `bool` return value
//!
//! Projects that previously returned a plain `bool` can adopt the error-code scheme with minimal
//! change: define exactly one non-success code (e.g. `const CERROR_FAIL: CError = 1;`) and map
//! *every* error type to it via `From<UserError> for CError`. The result is equivalent to a `bool`
//! -- [`CERROR_OK`] for success, `CERROR_FAIL` for any failure -- while leaving room to introduce
//! finer-grained codes later.
//!
//! # Required trait implementations
//!
//! [`set_last_error`] accepts any error type `E` that implements `Into<CError>` (typically provided
//! by implementing `From<UserError> for CError`) and [`Display`] (used to derive the message text).
use std::cell::RefCell;
use std::ffi::{CString, c_char};
use std::fmt::Display;
/// The raw pointer type to an immutable C/C++ NUL-terminated character string, as returned by
/// [`get_error_message`].
pub type CStrPtr = *const c_char;
/// The error code type returned by FFI functions.
///
/// This is a plain `u32`. [`CERROR_OK`] is the single value that represents absolute, unambiguous
/// success. Any other value's meaning is defined by the consuming project through
/// `From<UserError> for CError`: it may represent a failure, or, like some Win32 functions, a
/// *partial success*.
pub type CError = u32;
/// The sole error code that represents absolute, unambiguous success.
///
/// All other [`CError`] values carry project-defined meaning (failure or partial success) via the
/// user's `From<UserError> for CError`.
pub const CERROR_OK: CError = 0;
struct LastError {
/// `None` means nothing has been recorded since the last clear (i.e. the last call was an
/// absolute success). `Some(code)` means an outcome code has been recorded.
code: Option<CError>,
/// Cached message text derived from the error's [`Display`], with interior NUL bytes replaced
/// by the replacement character so that building the [`CString`] never fails.
msg: CString,
}
impl LastError {
fn new() -> Self {
Self {
code: None,
msg: CString::new("").expect("empty string must be valid for CString"),
}
}
pub fn set_msg(&mut self, msg: &str) {
self.msg = CString::new(msg).expect("unexpected blank in error message output");
/// Record an outcome: derive a message from `err`'s [`Display`] (sanitizing interior NUL) and
/// store `err.into()` as the code.
pub fn set_last_error<E: Into<CError> + Display>(&mut self, err: E) {
let text = format!("{err}").replace('\0', "\u{FFFD}");
self.msg = CString::new(text).expect("NUL bytes were sanitized away");
self.code = Some(err.into());
}
pub fn get_msg(&self) -> *const c_char {
self.msg.as_ptr()
}
pub fn clear_msg(&mut self) {
/// Reset to the absolute-success state: no code, empty message.
pub fn clear_last_error(&mut self) {
self.code = None;
self.msg = CString::new("").expect("empty string must be valid for CString");
}
/// Return whether an outcome has been recorded since the last clear.
pub fn has_last_message(&self) -> bool {
self.code.is_some()
}
/// Return the recorded code, or [`CERROR_OK`] (absolute success) if none was recorded.
pub fn get_error_code(&self) -> CError {
self.code.unwrap_or(CERROR_OK)
}
/// Return a pointer to the cached message string -- a NUL-terminated C string whose storage is
/// private to this module and not shared with any other module's cache. If nothing was recorded
/// the pointer addresses an empty string. The pointer stays valid until the next
/// [`set_last_error`](Self::set_last_error) or [`clear_last_error`](Self::clear_last_error) on
/// this thread.
pub fn get_error_message(&self) -> CStrPtr {
self.msg.as_ptr()
}
}
thread_local! {
static LAST_ERROR: RefCell<LastError> = RefCell::new(LastError::new());
}
/// Set thread local error message.
pub fn set_last_error(msg: &str) {
LAST_ERROR.with(|e| {
e.borrow_mut().set_msg(msg);
});
/// Record an outcome for the current thread.
///
/// Derives a message from `err`'s [`Display`] (interior NUL bytes are replaced with the replacement
/// character) and stores `err.into()` as the code. Requires `E: Into<CError> + Display`.
pub fn set_last_error<E: Into<CError> + Display>(err: E) {
LAST_ERROR.with(|e| e.borrow_mut().set_last_error(err));
}
/// Get const pointer to thread local error message string.
/// If there is no error, return pointer will point to empty string.
pub fn get_last_error() -> *const c_char {
LAST_ERROR.with(|e| e.borrow().get_msg())
}
/// Clear thread local error message (reset to empty string).
/// Reset the current thread's recorded outcome to the absolute-success state (no code, empty
/// message). Should be called at the entry of every FFI function.
pub fn clear_last_error() {
LAST_ERROR.with(|e| {
e.borrow_mut().clear_msg();
});
LAST_ERROR.with(|e| e.borrow_mut().clear_last_error());
}
/// Return whether an outcome has been recorded for the current thread since the last clear.
pub fn has_last_message() -> bool {
LAST_ERROR.with(|e| e.borrow().has_last_message())
}
/// Return the current thread's recorded code, or [`CERROR_OK`] (absolute success) if none was
/// recorded.
pub fn get_error_code() -> CError {
LAST_ERROR.with(|e| e.borrow().get_error_code())
}
/// Return a pointer to the current thread's cached message string -- a NUL-terminated C string
/// whose storage is private to this module and not shared with any other module's cache. If nothing
/// was recorded the pointer addresses an empty string. The pointer stays valid until the next
/// [`set_last_error`] or [`clear_last_error`] on this thread.
pub fn get_error_message() -> CStrPtr {
LAST_ERROR.with(|e| e.borrow().get_error_message())
}
omrf/src/lib.rs
+1 -120
View File
@@ -1,28 +1,8 @@
pub mod cffi;
pub mod cstr_ffi;
pub mod last_error;
pub mod object_pool;
#[macro_export]
macro_rules! in_param_ty {
($t:ty) => {
$t
};
}
#[macro_export]
macro_rules! out_param_ty {
($t:ty) => {
*mut $t
};
}
#[macro_export]
macro_rules! set_out_param {
($lhs:expr, $rhs:expr) => {
unsafe { *$lhs = $rhs };
};
}
#[macro_export]
macro_rules! resolve_enum {
($t:ty, $v:expr) => {
@@ -43,102 +23,3 @@ macro_rules! pull_writer {
$pool.write().map_err(|_| Error::PoisonRwLock)
};
}
/// Macro to wrap inner function execution with standard error handling pattern.
///
/// For functions with no output parameter and no input parameters:
/// ```ignore
/// cffi_wrapper!(|| {
/// // inner function body returning Result<()>
/// });
/// ```
///
/// For functions with no output parameter and with input parameters:
/// ```ignore
/// cffi_wrapper!(|param1: Type1, param2: Type2| {
/// // inner function body using param1, param2 returning Result<()>
/// });
/// ```
///
/// For functions with one output parameter and no input parameters:
/// ```ignore
/// cffi_wrapper!(|| -> (out_param, OutType) {
/// // inner function body returning Result<T>
/// });
/// ```
///
/// For functions with one output parameter and with input parameters:
/// ```ignore
/// cffi_wrapper!(|param1: Type1| -> (out_param, OutType) {
/// // inner function body using param1 returning Result<T>
/// });
/// ```
#[macro_export]
macro_rules! cffi_wrapper {
// Case with output parameter and input parameters
(|$($param:ident: $param_ty:ty),*| -> ($out_param:ident: $out_param_ty:ty) $inner_body:block) => {{
fn inner($($param: $param_ty),*) -> Result<$out_param_ty> $inner_body
match inner($($param),*) {
Ok(rv) => {
set_out_param!($out_param, rv);
last_error::clear_last_error();
true
}
Err(e) => {
last_error::set_last_error(e.to_string().as_str());
false
}
}
}};
// Case with output parameter and no input parameters
(|| -> ($out_param:ident: $out_param_ty:ty) $inner_body:block) => {{
fn inner() -> Result<$out_param_ty> $inner_body
match inner() {
Ok(rv) => {
set_out_param!($out_param, rv);
last_error::clear_last_error();
true
}
Err(e) => {
last_error::set_last_error(e.to_string().as_str());
false
}
}
}};
// Case without output parameter but with input parameters
(|$($param:ident: $param_ty:ty),*| $inner_body:block) => {{
fn inner($($param: $param_ty),*) -> Result<()> $inner_body
match inner($($param),*) {
Ok(_) => {
last_error::clear_last_error();
true
}
Err(e) => {
last_error::set_last_error(e.to_string().as_str());
false
}
}
}};
// Case without output parameter and no input parameters
(|| $inner_body:block) => {{
fn inner() -> Result<()> $inner_body
match inner() {
Ok(_) => {
last_error::clear_last_error();
true
}
Err(e) => {
last_error::set_last_error(e.to_string().as_str());
false
}
}
}};
}