A simple plugin interface for the Rust FFI

External function types

The external function types are defined as follows:

#[repr(C)]
struct Object {
    _private: [u8; 0],
}
type FreeObject = extern "C" fn(*mut Object);
type Init = extern "C" fn() -> *mut Object;
type GetApiVersion = extern "C" fn() -> c_int;
type GetInfo = extern "C" fn(*const Object) -> c_int;
type SetInfo = extern "C" fn(*mut Object, c_int);

The opaque struct from the C library is represented as rust struct with a single, private field containing an empty array. This is currently the recommended way to represent opaque structs in the Rust FFI. Following the struct definition are the type definitions for the foreign functions.

type FreeObject = extern "C" fn(*mut Object);
type Init = extern "C" fn() -> *mut Object;
// ...

For example, the Init type represents a foreign C function that takes no arguments and returns a mutable raw pointer to an Object instance. This function type therefore represents the Object constructor in Rust.

The VTable

The VTable serves as a way to collect the types associated with the C library functions into one place. Furthermore, I added a version number to make it VTableV0. The purpose in doing this is to easily maintain backwards compatability with and follow changes to the C API.

By looking at its definition, you can see that it contains a few RawSymbol instances:

struct VTableV0 {
    free_object: RawSymbol<FreeObject>,
    get_info: RawSymbol<GetInfo>,
    set_info: RawSymbol<SetInfo>,
}

A RawSymbol is a name that I gave to Unix-specific symbols from the libloading Rust library. (See the use statements at the top of the source code file.) I am not storing plain Symbols from that library inside the VTable because the lifetime constraints associated with plain Symbols and their corresponding Library do not allow me to take ownership of them inside the struct. (You can find a few attempts in the commit history of this repository where I tried to own plain Symbols; none of these attempts would compile.)

Instead, if I had used a plain Symbol, then I would have had to lookup the symbols inside the C library each time that I wanted to call them.

The way to obtain RawSymbols is to use the into_raw method of a plain Symbol. You can find an example of this inside the VTable's constructor:

unsafe fn new(library: &Library) -> VTableV0 {
    println!("Loading API version 0...");
    let free_object: Symbol<FreeObject> = library.get(b"free_object\0").unwrap();
    let free_object = free_object.into_raw();
    // ...

First, the free_object Symbol is imported from the library using the get() method from the library, then it is converted to a RawSymbol in the following line so that it can be stored inside the VTableV0 struct that is returned by the constructor. The whole function is marked as unsafe because of the multiple calls to the get method.

The Plugin

Finally we reach the top of the hierarchy of the components that comprise this design, the Plugin struct. Its implementation follows:

struct Plugin {
    #[allow(dead_code)]
    library: Library,
    object: *mut Object,
    vtable: VTableV0,
}

impl Plugin {
    unsafe fn new(library_name: &OsStr) -> Plugin {
    let library = Library::new(library_name).unwrap();
        let get_api_version: Symbol<GetApiVersion> = library.get(b"get_api_version\0").unwrap();
        let vtable = match get_api_version() {
            0 => VTableV0::new(&library),
            _ => panic!("Unrecognized C API version number."),
        };

        let init: Symbol<Init> = library.get(b"init\0").unwrap();
        let object: *mut Object = init();

        Plugin {
            library: library,
            object: object,
            vtable: vtable,
        }
    }
}

impl Drop for Plugin {
    fn drop(&mut self) {
        (self.vtable.free_object)(self.object);
    }
}

The interesting parts here are the Plugin's constructor new and the implementation of the Drop trait. After loading the library, the constructor calls the C library function that returns its API version; if the version matches one for which we have a VTable, then we create the new VTable. Next, we instantiate an Object by calling its constructor to obtain a raw pointer to it.

let init: Symbol<Init> = library.get(b"init\0").unwrap();
let object: *mut Object = init();

The constructor packs the library, the VTable, and the object pointer into a new Plugin struct and returns it.

The Drop trait implementation is used to automatically free the memory that has been allocated when the pointer held by the Plugin struct goes out-of-scope. It does this by calling the free_object method in the VTable.

impl Drop for Plugin {
    fn drop(&mut self) {
        (self.vtable.free_object)(self.object);
    }
}

Running the example

To run the example, run the following commands from the root directory of the example repository.

$ cargo build
Compiling rust-libloading v0.1.0 (/home/kmdouglass/src/rust-libloading-example)
 Finished dev [unoptimized + debuginfo] target(s) in 0.27s
$ cargo run
 Finished dev [unoptimized + debuginfo] target(s) in 0.01s
  Running `target/debug/rust-libloading`
Loading API version 0...
Original value: 0
New value: 42

The main method of the Rust code creates the plugin, prints the default value of the data held by the object (which is instantiated by the C library), and then mutates the data to the value 42.

It then prints this value, demonstrating that the FFI calls work.