Rust FFI Omnibus

Returning an allocated string from Rust to another language is complex because the Rust allocator may differ from the caller's allocator. To safely return a string, you must transfer ownership to the caller via a raw pointer, and the caller must eventually return that pointer to Rust to ensure the memory is properly deallocated.

In Rust, use CString::into_raw to convert a CString into a raw pointer for FFI. To reclaim ownership and deallocate the memory later, the caller must pass that pointer back to a Rust function that uses CString::from_raw.

// Rust side logic pattern
// 1. Create CString
// 2. Call .into_raw() to pass ownership to caller
// 3. Caller must eventually pass pointer back to Rust to call CString::from_raw()

In C#, wrap the Rust string in a subclass of SafeHandle. Use a wrapper class to ensure the handle is disposed of properly.

Note: Since C# does not have a native way to read a pointer directly as a UTF-8 string (it supports ANSI and UCS-2/Unicode), you must implement a custom method to read the pointer as UTF-8.

// C# pattern
// Wrap in SafeHandle and use a wrapper to ensure disposal

When calling Rust FFI functions from other languages, the system must be able to locate the compiled dynamic library. The method for doing this depends on your operating system:

macOS and Linux

Prefix your execution command with LD_LIBRARY_PATH pointing to the directory containing your compiled library (typically target/debug).

Note: On macOS, System Integrity Protection (SIP) may prevent setting LD_LIBRARY_PATH for system-provided binaries. You may need to use a different binary or disable SIP.

Windows

Copy the compiled .dll file directly into the current working directory before running your application.

# macOS/Linux example
LD_LIBRARY_PATH=target/debug python src/main.py

To use the integer library, compile the Rust source using cargo build. This generates a dynamic library in target/debug/. The filename pattern varies by platform:

• Windows: *.dll
• macOS: lib*.dylib
• Linux: lib*.so

In Julia, use the Cstring data type to represent the NUL-terminated string. To avoid managing the Rust-allocated memory directly in Julia, use unsafe_string to construct a copy of the string that is managed by Julia's garbage collector, then transfer the original Rust pointer back to Rust to be freed.

# Julia pattern
ptr = get_string_ffi()
if ptr != C_NULL
    str = unsafe_string(ptr)
    free_rust_string(ptr)
end

When calling the FFI method in Haskell, first check if the returned pointer is NULL. If it is not NULL, use peekCString to convert the pointer into a Haskell String, and then immediately call the Rust function to free the string.

-- Haskell pattern
ptr <- get_string_ffi
if ptr == nullPtr
    then return ""
    else do
        str <- peekCString ptr
        free_rust_string ptr
        return str

In Node.js, wrap the FFI functions in a class to provide an idiomatic JavaScript API (e.g., camelCase) and manage the pointer lifecycle.

Implementation Steps:

1. Declare the pointer type for returned or accepted arguments in your FFI definitions.
2. Create a wrapper class that maintains the pointer.
3. Use a try...finally block in your application code to ensure the deallocation method is called in the finally block, preventing leaks.

const db = new ZipCodeDatabase();
try {
  const pop = db.getPopulation(zipCode);
} finally {
  db.free();
}

For robust memory management in C#, inherit from System.Runtime.InteropServices.SafeHandle. This integrates the Rust pointer into the .NET lifecycle and ensures it is released correctly.

Implementation Steps:

1. Create a Native class to hold the FFI function definitions.
2. Create a subclass of SafeHandle (e.g., ZipCodeDatabaseHandle).
3. Implement IsInvalid (returning false if your Rust function accepts NULL) and ReleaseHandle (calling the Rust deallocation function).
4. Implement the IDisposable pattern on your high-level wrapper to forward disposal to the SafeHandle.

class ZipCodeDatabaseHandle : SafeHandle {
    public override bool IsInvalid => IsNull;
    protected override bool ReleaseHandle() {
        Native.zip_code_database_free(handle);
        return true;
    }
}

In Julia, hide the handler pointer behind a new data type. You can manage the lifecycle using either a mapping constructor (for do blocks) or a manual close method.

Implementation Steps:

1. Define a type that wraps the pointer.
2. Option 1 (Automatic): Implement a mapping constructor ZipCodeDatabase(f) that handles both allocation and deallocation. This allows usage with the do syntax, similar to Python's with.
3. Option 2 (Manual): Implement a close method to manually free the object when it is no longer needed.

# Option 1: Using 'do' syntax (Automatic)
zip_code_database(zip) do db
    pop = get_population(db, zip)
end

# Option 2: Manual closing
db = ZipCodeDatabase()
# ... use db ...
close(db)