C API Reference

The C API (exposed via a cbindgen-generated header) provides stable, binary-compatible access to the core rsx_core functionality from C, C++, Python (ctypes / cffi), R (.Call), and other languages.

It follows a simple contract (see also the Architecture page):

  • All public types are #[repr(C)].

  • Functions return rsx_status_t first.

  • Thread-local error details via rsx_last_error().

  • Opaque handles for complex state (e.g. popmaps, marker tables in future).

  • Naming: rsx_ prefix, SCREAMING_SNAKE_CASE for enums, _t suffix for structs.

1 Building the header

cargo build --manifest-path rsxcore/Cargo.toml --features gen-header
# Produces rsxcore/include/rsx.h

The header is a build artifact (gitignored) and must be regenerated after changes to the C API surface in rsxcore/src/c_api/.

2 API Reference

3 Error handling

All fallible functions return an rsx_status_t. On failure, call rsx_last_error() on the same thread to retrieve a human-readable message (the pointer is valid only until the next C API call on that thread).

4 Cross-language notes

  • C/C++: Link against the cdylib (librsx_core.so / .dylib / .dll) and include the header.

  • Python: Use ctypes or cffi to load the library and call the functions (see the R-integration how-to for a similar pattern). Prefer the pyrsx package for notebooks and pipelines.

  • R: Prefer the in-process rsxr package (.Call into the static library). Raw dyn.load of the shared object is possible but unsupported.

For the underlying Rust implementation of these functions and types, see the Rust API Reference.