Rust FFI Guide

This guide provides a deep dive into advanced Foreign Function Interface (FFI) tasks, moving beyond simple function calls to complex integrations. The primary use case demonstrated is building a REST client where a Qt GUI (C++) calls into a Rust library for business logic.

Key learning objectives include:

• Integrating cargo into a larger build system (e.g., cmake).
• Calling Rust functions from C++ or other languages.
• Passing complex data types like strings, structs, and arrays between Rust and C++.
• Implementing robust error handling and exception safety.
• Creating a C-compatible interface for a Rust library.
• Handling multithreading and asynchronous programming to prevent UI blocking.
• Creating abstractions to encapsulate common FFI patterns.

For developers looking to implement these patterns immediately, the ffi-helpers crate is available to provide the abstractions discussed in this guide.

Dynamic loading allows an application to load a shared library (like a .so or .dll) at runtime and call functions exported by that library.

To use this pattern:

1. Compile the library as a cdylib: You must use the cdylib crate type so the compiler produces a compatible dynamic library.
2. Export symbols: Use #[no_mangle] and pub extern "C" on functions you want to access from the host application.
3. Load the library: Use the libloading crate to load the file and retrieve symbols.
4. Cast symbols: Use a type alias for the function signature to ensure type safety when calling the loaded symbol via libloading::Symbol.

# Compile a Rust file as a dynamic library
rustc --crate-type cdylib adder.rs

// Example of loading a symbol
type AddFunc = unsafe fn(isize, isize) -> isize;

fn main() {
    let library_path = "../libadder.so";
    let lib = libloading::Library::new(library_path).unwrap();

    unsafe {
        let func: libloading::Symbol<AddFunc> = lib.get(b"add").unwrap();
        let answer = func(1, 2);
        println!("1 + 2 = {}", answer);
    }
}

To build the Rust library transparently during the CMake build process, create a client/CMakeLists.txt that invokes cargo build.

Implementation details:

1. Build Type Handling: Use an if statement on CMAKE_BUILD_TYPE to switch between cargo build (Debug) and cargo build --release (Release).
2. Target Directory Management: Set the CARGO_TARGET_DIR environment variable to a path within the CMake build directory to keep build artifacts organized.
3. Custom Target: Use add_custom_target to run the cargo command and cp the resulting .so file into the CMake binary directory.
4. Location Property: Set the LOCATION property on the client target so other CMake targets (like gui) can find the library path using get_target_property.

# client/CMakeLists.txt

if (CMAKE_BUILD_TYPE STREQUAL "Debug")
    set(CARGO_CMD cargo build)
    set(TARGET_DIR "debug")
else ()
    set(CARGO_CMD cargo build --release)
    set(TARGET_DIR "release")
endif ()

set(CLIENT_SO "${CMAKE_CURRENT_BINARY_DIR}/${TARGET_DIR}/libclient.so")

add_custom_target(client ALL
    COMMENT "Compiling client module"
    COMMAND CARGO_TARGET_DIR=${CMAKE_CURRENT_BINARY_DIR} ${CARGO_CMD} 
    COMMAND cp ${CLIENT_SO} ${CMAKE_CURRENT_BINARY_DIR}
    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
set_target_properties(client PROPERTIES LOCATION ${CMAKE_CURRENT_BINARY_DIR})

add_test(NAME client_test 
    COMMAND cargo test
    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})

Once cbindgen generates a header file (e.g., client.hpp) in your Rust target/ directory, you must configure CMake to include that directory in its search path so your C++ code can #include it.

In your CMakeLists.txt, set the include directory to the location where the header is generated:

set(CLIENT_BUILD_DIR ${CMAKE_BINARY_DIR}/client)
include_directories(${CLIENT_BUILD_DIR})

After configuring CMake, you can update your C++ source files to:

1. #include "client.hpp".
2. Remove manual extern "C" blocks.
3. Prefix Rust function calls with the namespace defined in your build.rs (e.g., ffi::initialize_logging()).

set(CMAKE_INCLUDE_CURRENT_DIR ON)
find_package(Qt5Widgets)

set(CLIENT_BUILD_DIR ${CMAKE_BINARY_DIR}/client)
include_directories(${CLIENT_BUILD_DIR})

set(SOURCE main_window.cpp main_window.hpp wrappers.cpp wrappers.hpp main.cpp)

add_executable(gui ${SOURCE})

To avoid using non-idiomatic and error-prone raw C-style bindings in your C++ application, create a wrapper class. This allows you to use C++ features like destructors for automatic memory management and std::string for easier input handling.

1. Header (wrappers.hpp): Define a class that holds a void* (or a pointer to the opaque type) representing the raw Rust object.
2. Implementation (wrappers.cpp):
   • Use extern "C" blocks to declare the raw Rust functions.
   • In the constructor, call the Rust creation function and convert the input to a C-style string using .c_str().
   • In the destructor, call the Rust destruction function to prevent memory leaks.
3. Error Handling: Check if the raw pointer returned by Rust is nullptr and throw a C++ exception if it is.

// gui/wrappers.hpp
#include <string>

class Request {
public:
  Request(const std::string);
  ~Request();

private:
  void *raw;
};

// gui/wrappers.cpp
#include "wrappers.hpp"

extern "C" {
void *request_create(const char *);
void request_destroy(void *);
}

Request::Request(const std::string url) {
  raw = request_create(url.c_str());
  if (raw == nullptr) {
    throw "Invalid URL";
  }
}

Request::~Request() { request_destroy(raw); }

To expose a Rust struct (like Request) to C++, you must hide it behind a raw pointer because the C interface cannot handle Rust-specific features like generics.

1. Constructor: Use Box::new() to move the struct to the heap, then call Box::into_raw() to return a raw pointer to the caller.
2. Destructor: Accept the raw pointer, convert it back to a Box using Box::from_raw(), and allow the Box to be dropped to ensure memory is freed.
3. Naming Convention: Prefix functions with the type name (e.g., request_create, request_destroy) to simulate method ownership.
4. Error Handling: When converting C strings (*const c_char) to Rust types (like Url), return a null pointer (ptr::null_mut()) if the conversion fails.

// client/src/ffi.rs

#[no_mangle]
pub unsafe extern "C" fn request_create(url: *const c_char) -> *mut Request {
    if url.is_null() {
        return ptr::null_mut();
    }

    let raw = CStr::from_ptr(url);

    let url_as_str = match raw.to_str() {
        Ok(s) => s,
        Err(_) => return ptr::null_mut(),
    };

    let parsed_url = match Url::parse(url_as_str) {
        Ok(u) => u,
        Err(_) => return ptr::null_mut(),
    };

    let req = Request::new(parsed_url, Method::Get);
    Box::into_raw(Box::new(req))
}

#[no_mangle]
pub unsafe extern "C" fn request_destroy(req: *mut Request) {
    if !req.is_null() {
        drop(Box::from_raw(req));
    }
}