chillffi 0.1.0 - Docs.rs

chillffi

A simple isolated dynamic FFI framework for Rust

chillffi allows dynamically loading C libraries .so and calling their functions at runtime, isolating the calls in a separate empty process.

If third-party C code crashes or corrupts something, your main Rust application will continue running.

(In the future, an expansion of the functionality for working with FFI is planned.)

✨ Features

🛡️ Crash Isolation: A crash or panic inside unreliable FFI code does not break or corrupt the main process.
⚡ Zygote Model (Zygote): Fast forking and spawning of isolated workers with minimal overhead.
🚀 In-memory IPC: Transfer of file descriptors and data through sockets without accessing the disk.
🧩 Dynamic FFI: On-the-fly function calls without the need to compile static C bindings.

📦 Installation

Add the dependency to Cargo.toml:

Note: supported only on Unix-like OSes, and tested only on Linux.

(Planned: Windows, macOS, WASM, Bare metal.)

🚀 Quick Start

Example of a safe call to the sqrt function from the system library libm.so.6 using the ffi!{} macro and explicit typing:

fn main() -> ()
{
  // Perform an FFI call inside an isolated context using a macro
  let result: Value = ffi!{
    // 1. Dynamically load the system library
    let libm: Library = Library::load("libm.so.6")?;
  
    // 2. Prepare the argument vector
    let args: Vec<Value> = vec![Value::F64(4.0)];
  
    // 3. Call the "sqrt" function, specifying the expected return type Type::F64
    Ok(libm.call("sqrt", args, Type::F64)?)
    
    // Here libm will be automatically cleared due to drop() when exiting the closure.
    // You can also do this manually via drop(libm) or libm.unload()?
  }.expect("FFI call failed");

  // Process the typed result
  match result
  {
    Value::F64(val) => 
    {
      println!("sqrt(4.0) = {}", val);
      assert!((val - 2.0).abs() < f64::EPSILON, "sqrt(4.0) != 2.0");
    }
    _ => panic!("Unexpected return type for sqrt"),
  }
}

For memory-sensitive operations — C strings, out-parameters, or raw buffers — use the scoped variant with Scope and AllocatedMemory:

fn main() -> ()
{
  // clock_gettime(CLOCK_REALTIME, &timespec) — struct out-param via Alloc/ReadMemory,
  // the case a plain Value::Pointer can't cover on its own.
  let (secs, nanos): (i64, i64) = ffi!(|scope| {
    let libc: Library = Library::load("libc.so.6")?;

    // struct timespec { time_t tv_sec; long tv_nsec; } — 16 bytes on x86_64 Linux
    let mem: AllocatedMemory = scope.alloc(16)?;

    libc.call("clock_gettime", vec![Value::I32(0 /* CLOCK_REALTIME */), mem.asPointer()], Type::I32)?;

    let Value::RawString(bytes) = mem.read()? else { 
      panic!("expected bytes")
    };
    drop(mem);

    let secs: i64 = i64::from_ne_bytes(bytes[0..8].try_into().unwrap());
    let nanos: i64 = i64::from_ne_bytes(bytes[8..16].try_into().unwrap());
    Ok((secs, nanos))
  }).expect("clock_gettime failed");

  println!("clock_gettime(CLOCK_REALTIME) = {}.{:09}", secs, nanos);
}

For more detailed examples, see the examples folder.

You can also run them via cargo run --example <name>.

⚡ Why is this convenient

In general practice, we are used to doing it like in Python and other programming languages - precisely specifying all the wrappers for FFI. After which we observe how FFI still crashes anyway and the libraries are not built, and the code does not work.

This is all because FFI requires a manual bridge and it is not always possible to make one.

chillffi works on a different principle - you can write any FFI code inside isolated blocks. Because FFI should not be scattered throughout your code - this is an unsafe approach. Therefore, we write it in isolation and preferably briefly, only when necessary.

Since everything is located in isolated processes - we do not damage the main runtime in any way and do not touch your code. All FFI requests work in a sterile manner and in case of errors will clearly let you know about it. You can also simply ignore them if you want.

As a result, we can freely and simply write:

Test code
Educational code
FFI bridges
Dynamic programming languages
Game engines
Reactive systems and dynamic systems
And many other things

This is also different from the WASM approach - because we preserve a true native execution here.

🛠️ How it works

Before your code starts running, a Zygote is created - it is an empty process for cloning itself and isolating FFI.
When work with FFI is required - a copy is created from the zygote.
Data and descriptors are transferred through a secure socket channel in memory.
In case of errors, the supervisor intercepts the worker crash and returns the error to Rust, keeping your application stable.

📄 License

The source code is distributed under the FCL license. This is a custom license of the RTS programming language.

In addition, chillffi is distributed under this license because the source code was originally taken from the RTS language itself. Therefore, chillffi inherits this license.

For a more accurate understanding, you should familiarize yourself with the text of the license.

But if very simply, for those who just work and want to use it:

Personal/non-commercial use → free
Commercial use without modifications → free
Commercial use with modifications → requires the author's permission or opening the changes

Keep this in mind for your projects.