fix(ffi): return parser status and isolate thread errors

This commit is contained in:
Jan Petykiewicz 2026-11-14 14:23:13 -08:00
commit 24438c4840
5 changed files with 234 additions and 24 deletions

View file

@ -20,4 +20,14 @@ A fast GDSII parser and writer in Rust, with Apache Arrow integration for effici
## Usage
(To be added)
`read_path` exports a library through the Arrow C Data Interface. Allocate
initialized `ArrowArray` and `ArrowSchema` output structures, then check the
returned status: `0` means success and `-1` means failure. Only import the Arrow
outputs after success; the caller owns their release callbacks. Failed calls
leave the outputs unchanged. See `test.py` for a Python CFFI example.
`last_error_message()` returns a UTF-8, null-terminated error string, or null
after a successful parser call. Errors belong to the calling thread. Copy the
message before making another parser call on that thread, and before the thread
exits; calls on other threads do not invalidate it. Parser panics that unwind
are converted into errors.

View file

@ -9,38 +9,127 @@ pub mod library;
use crate::library::read_library;
use byteorder::{ByteOrder, BigEndian};
use std::any::Any;
use std::cell::RefCell;
use std::mem::size_of;
use std::ffi::{CStr, OsStr, c_char};
use std::os::unix::ffi::OsStrExt;
use std::ffi::{CStr, CString, c_char};
use std::panic::{AssertUnwindSafe, catch_unwind};
use std::path::{Path, PathBuf};
use std::ptr;
#[cfg(unix)]
use std::os::unix::ffi::OsStringExt;
use std::str;
use std::fs;
use std::path::Path;
use arrow::ffi::{to_ffi, FFI_ArrowArray, FFI_ArrowSchema};
use arrow::array::Array;
use arrow::array::{Array, StructArray};
thread_local! {
static LAST_ERROR: RefCell<Option<CString>> = const { RefCell::new(None) };
}
fn clear_last_error() {
LAST_ERROR.with(|last_error| *last_error.borrow_mut() = None);
}
fn set_last_error(message: String) -> i32 {
let sanitized = message.replace('\0', "\\0");
LAST_ERROR.with(|last_error| *last_error.borrow_mut() = Some(CString::new(sanitized).unwrap()));
-1
}
fn describe_panic(payload: Box<dyn Any + Send>) -> String {
if let Some(message) = payload.downcast_ref::<&str>() {
(*message).to_string()
} else if let Some(message) = payload.downcast_ref::<String>() {
message.clone()
} else {
"unexpected panic".to_string()
}
}
fn export_struct_array(
op_name: &str,
arr: *mut FFI_ArrowArray,
schema: *mut FFI_ArrowSchema,
build: impl FnOnce() -> Result<StructArray, String>,
) -> i32 {
clear_last_error();
if arr.is_null() || schema.is_null() {
return set_last_error(format!("{op_name}: Arrow output pointer was null"));
}
match catch_unwind(AssertUnwindSafe(build)) {
Ok(Ok(struct_arr)) => match to_ffi(&struct_arr.to_data()) {
Ok((ffi_arr, ffi_schema)) => {
unsafe {
*arr = ffi_arr;
*schema = ffi_schema;
}
0
},
Err(err) => set_last_error(format!("{op_name}: failed to export Arrow data: {err}")),
},
Ok(Err(message)) => set_last_error(format!("{op_name}: {message}")),
Err(payload) => set_last_error(format!("{op_name}: {}", describe_panic(payload))),
}
}
fn pathbuf_from_c(cpath: *const c_char) -> Result<PathBuf, String> {
if cpath.is_null() {
return Err("path pointer was null".to_string());
}
let cstr = unsafe { CStr::from_ptr(cpath) };
#[cfg(unix)]
{
return Ok(PathBuf::from(std::ffi::OsString::from_vec(cstr.to_bytes().to_vec())));
}
#[cfg(windows)]
{
let ustr = str::from_utf8(cstr.to_bytes())
.map_err(|_| "Non-UTF8 paths are not supported".to_string())?;
return Ok(PathBuf::from(ustr));
}
#[allow(unreachable_code)]
Err("Unsupported OS".to_string())
}
/// Return this thread's last parser error, or null if its last call succeeded.
/// The returned string remains valid until this thread's next parser call or exit.
#[unsafe(no_mangle)]
pub extern "C" fn last_error_message() -> *const c_char {
LAST_ERROR.with(|last_error| last_error.borrow()
.as_ref()
.map_or(ptr::null(), |message| message.as_ptr()))
}
/// Read a GDSII file and export its Arrow data. Return 0 on success or -1 on error.
///
/// # Safety
/// `cpath` must point to a null-terminated path. Non-null output pointers must
/// point to initialized, writable Arrow FFI structures. Null pointers are rejected.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn read_path(
cpath: *const c_char,
arr: *mut FFI_ArrowArray,
schema: *mut FFI_ArrowSchema,
) {
let cstr = unsafe { CStr::from_ptr(cpath) };
let path: &Path;
if cfg!(unix) {
let osstr = OsStr::from_bytes(cstr.to_bytes());
path = osstr.as_ref();
} else if cfg!(windows) {
let ustr = str::from_utf8(cstr.to_bytes()).expect("Non-UTF8 paths are not supported");
path = ustr.as_ref();
} else {
panic!("Unsupported OS");
}
let input = fs::read(path).expect("File read failed");
let (_input, struct_arr) = read_library(&input).expect("Read failed");
unsafe { (*arr, *schema) = to_ffi(&struct_arr.to_data()).unwrap(); }
) -> i32 {
export_struct_array("read_path", arr, schema, || {
let path = pathbuf_from_c(cpath)?;
let input = fs::read(Path::new(&path))
.map_err(|err| format!("file read failed for {}: {err}", path.display()))?;
let (_input, struct_arr) = read_library(&input)
.map_err(|err| format!("read failed: {err:?}"))?;
Ok(struct_arr)
})
}
@ -116,4 +205,3 @@ pub unsafe extern "C" fn u16_to_i16(arr: *mut u16, size: usize) -> u16 { impl_i1
#[unsafe(no_mangle)]
pub unsafe extern "C" fn i16_to_i16(arr: *mut i16, size: usize) -> i16 { impl_i16be!(i16, arr, size) }

10
test.py
View file

@ -16,10 +16,16 @@ clib = ffi.dlopen('target/debug/libklamath_rs_ext.so')
ret_ptr_array = ffi.new('struct ArrowArray[]', 1)
ret_ptr_schema = ffi.new('struct ArrowSchema[]', 1)
ffi.cdef('void read_path(char* path, struct ArrowArray* array, struct ArrowSchema* schema);')
ffi.cdef('''
int read_path(const char* path, struct ArrowArray* array, struct ArrowSchema* schema);
const char* last_error_message(void);
''')
print(f'{ret_ptr_array[0]=}, {ret_ptr_schema[0]=}')
clib.read_path(path.encode(), ret_ptr_array, ret_ptr_schema)
status = clib.read_path(path.encode(), ret_ptr_array, ret_ptr_schema)
if status != 0:
message = ffi.string(clib.last_error_message()).decode('utf-8', errors='replace')
raise RuntimeError(message)
ptr_schema = int(ffi.cast('uintptr_t', ret_ptr_schema))
ptr_array = int(ffi.cast('uintptr_t', ret_ptr_array))

20
tests/common/mod.rs Normal file
View file

@ -0,0 +1,20 @@
use klamath_rs_ext::{basic::encode_real8, records};
pub fn record(out: &mut Vec<u8>, tag: u16, data: &[u8]) {
out.extend_from_slice(&u16::try_from(data.len() + 4).unwrap().to_be_bytes());
out.extend_from_slice(&tag.to_be_bytes());
out.extend_from_slice(data);
}
pub fn library_header() -> Vec<u8> {
let mut bytes = Vec::new();
record(&mut bytes, records::RTAG_HEADER, &600_i16.to_be_bytes());
record(&mut bytes, records::RTAG_BGNLIB, &[0; 24]);
record(&mut bytes, records::RTAG_LIBNAME, b"test");
let units: Vec<u8> = [0.001, 1e-9]
.into_iter()
.flat_map(|v| encode_real8(v).unwrap().to_be_bytes())
.collect();
record(&mut bytes, records::RTAG_UNITS, &units);
bytes
}

86
tests/ffi_errors.rs Normal file
View file

@ -0,0 +1,86 @@
mod common;
use arrow::ffi::{FFI_ArrowArray, FFI_ArrowSchema};
use klamath_rs_ext::{last_error_message, read_path, records};
use std::{ffi::{CStr, CString}, fs, path::PathBuf, ptr};
struct TestFile(PathBuf);
impl TestFile {
fn new(name: &str, contents: &[u8]) -> Self {
let path = std::env::temp_dir().join(format!("klamath-{name}-{}.gds", std::process::id()));
fs::write(&path, contents).unwrap();
Self(path)
}
fn cpath(&self) -> CString {
CString::new(self.0.to_str().unwrap()).unwrap()
}
}
impl Drop for TestFile {
fn drop(&mut self) {
let _ = fs::remove_file(&self.0);
}
}
fn error_message() -> String {
let message = last_error_message();
assert!(!message.is_null());
unsafe { CStr::from_ptr(message) }.to_str().unwrap().to_owned()
}
#[test]
fn path_errors_preserve_outputs_and_convert_parser_panics() {
let mut array = FFI_ArrowArray::empty();
let mut schema = FFI_ArrowSchema::empty();
assert_eq!(unsafe { read_path(ptr::null(), &mut array, &mut schema) }, -1);
assert!(error_message().contains("path pointer was null"));
assert!(array.is_released());
// A mismatched timestamp size currently makes Record::read panic.
let mut bytes = Vec::new();
common::record(&mut bytes, records::RTAG_HEADER, &600_i16.to_be_bytes());
common::record(&mut bytes, records::RTAG_BGNLIB, &[0; 12]);
let file = TestFile::new("invalid-timestamps", &bytes);
assert_eq!(unsafe { read_path(file.cpath().as_ptr(), &mut array, &mut schema) }, -1);
assert!(error_message().contains("Expected record size"));
assert!(array.is_released());
let mut bytes = common::library_header();
common::record(&mut bytes, records::RTAG_ENDLIB, &[]);
let file = TestFile::new("valid-empty", &bytes);
assert_eq!(unsafe { read_path(file.cpath().as_ptr(), &mut array, &mut schema) }, 0);
assert!(!array.is_released());
assert!(last_error_message().is_null());
}
#[test]
fn other_threads_do_not_clear_or_free_error_messages() {
let mut array = FFI_ArrowArray::empty();
let mut schema = FFI_ArrowSchema::empty();
assert_eq!(unsafe { read_path(ptr::null(), &mut array, &mut schema) }, -1);
let pointer = last_error_message();
let message = error_message();
std::thread::spawn(|| {
assert!(last_error_message().is_null());
let mut bytes = common::library_header();
common::record(&mut bytes, records::RTAG_ENDLIB, &[]);
let file = TestFile::new("thread-empty", &bytes);
let mut array = FFI_ArrowArray::empty();
let mut schema = FFI_ArrowSchema::empty();
assert_eq!(unsafe { read_path(ptr::null(), &mut array, &mut schema) }, -1);
assert_eq!(unsafe { read_path(file.cpath().as_ptr(), &mut array, &mut schema) }, 0);
assert!(last_error_message().is_null());
}).join().unwrap();
assert_eq!(last_error_message(), pointer);
assert_eq!(unsafe { CStr::from_ptr(pointer) }.to_str().unwrap(), message);
}
#[test]
fn null_arrow_outputs_return_an_error() {
assert_eq!(unsafe { read_path(ptr::null(), ptr::null_mut(), ptr::null_mut()) }, -1);
assert!(error_message().contains("Arrow output pointer was null"));
}