diff --git a/README.md b/README.md index 3d5b1b1..9f65aaa 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/src/lib.rs b/src/lib.rs index 39081ab..59cada7 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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> = 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) -> String { + if let Some(message) = payload.downcast_ref::<&str>() { + (*message).to_string() + } else if let Some(message) = payload.downcast_ref::() { + 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, + ) -> 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 { + 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) } - diff --git a/test.py b/test.py index 788df2e..5421f47 100644 --- a/test.py +++ b/test.py @@ -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)) diff --git a/tests/common/mod.rs b/tests/common/mod.rs new file mode 100644 index 0000000..e0cc662 --- /dev/null +++ b/tests/common/mod.rs @@ -0,0 +1,20 @@ +use klamath_rs_ext::{basic::encode_real8, records}; + +pub fn record(out: &mut Vec, 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 { + 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 = [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 +} diff --git a/tests/ffi_errors.rs b/tests/ffi_errors.rs new file mode 100644 index 0000000..9d0bf73 --- /dev/null +++ b/tests/ffi_errors.rs @@ -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")); +}