Previously when the code-base was in C++, I had C++ wrapper files which would link to the code base and I would run swig (version 3 for C++11 support) to generate the interface files for the target language (Python, JavaScript, C#, etc.). Then of course get all these files and libraries compiled into a shared object and have it invoked from the required languages. Now the code base is being changed to rust. So for swig to work I have the following:
Main rust code file compiling into an rlib.
Rust wrapper file that calls into the main code base but uses no_mangle and extern syntax for FFI and compiles into a staticlib.
A C file that calls the rust wrapper and is a replica of it.
Now I use swig on the C file, get the interface file for the target language, combine all the files (steps two and three) and the SWIG interface file) into a shared object and call from the target language.
So:
Is the approach fine?
I can get free functions to work. However I'm confused on how to get member functions (methods) to work. In C++ the first parameter of the member functions is the implicit this pointer. So I could return a void* handle to the class or struct to the C interface which would pass it on to others who wanted to store it (e.g. jsctypes for Firefox) and then on receiving again reinterpret_cast it to the concrete/actual type and invoke the member function on it. How do I do this with Rust?
e.g., for
pub struct A { id: SomeType, }
impl A {
pub fn some_funct_0(&mut self) {}
pub fn some_funct_1(&self) {}
}
impl SomeTrait for A {
fn some_trait_funct(&mut self) {}
}
So how do I access these member functions on an object of A (should be unmanaged and on the heap I guess?) from target languages (Python, C, etc.) or even simply a C interface?
Well, methods are just regular functions, and as Chris said, self argument has implicit connection with Self type. With your example (slightly modified) using functions from C code should be straightforward:
#[repr(C)]
pub struct A { id: u32, }
#[no_mangle]
pub extern fn new_a(id: u32) -> A {
A { id: id }
}
impl A {
#[no_mangle]
pub extern fn some_funct(&self) {
println!("Called some_funct: {}", self.id);
}
}
trait SomeTrait {
extern fn some_trait_funct(&self);
}
impl SomeTrait for A {
#[no_mangle]
extern fn some_trait_funct(&self) {
println!("Called some_trait_funct: {}", self.id);
}
}
Note that I added extern to change calling convention and #[no_mangle] to avoid name mangling and #[repr(C)] on the struct. The latter is not necessary if your code creates Boxes of the struct and pass them to C as raw pointers. I'm not sure, however, how #[no_mangle] could affect trait methods if there is more than one trait implementor - if both have #[no_mangle], there is bound to be some kind of name conflict.
Now using this type and its functions from C is easy:
#include <stdint.h>
struct A {
uint32_t id;
};
extern struct A new_a(uint32_t id);
extern void some_funct(const struct A *self);
extern void some_trait_funct(const struct A *self);
int main() {
struct A a = new_a(123);
some_funct(&a);
some_trait_funct(&a);
}
This program compiles and works:
% rustc --crate-type=staticlib test.rs
multirust: a new version of 'nightly' is available. run `multirust update nightly` to install it
note: link against the following native artifacts when linking against this static library
note: the order and any duplication can be significant on some platforms, and so may need to be preserved
note: library: System
note: library: pthread
note: library: c
note: library: m
% gcc -o test_use test_use.c libtest.a -lSystem -lpthread -lc -lm
% ./test_use
Called some_funct: 123
Called some_trait_funct: 123
If methods accepted &mut self:
#[no_mangle]
extern fn some_funct_mut(&mut self) { ... }
you would need to omit const:
extern void some_funct_mut(struct A *self);
If methods accepted self:
#[no_mangle]
extern fn some_funct_value(self) { ... }
you would need to pass the structure by value:
extern void some_funct_value(struct A self);
Though if you use the structure through an opaque pointer, calling functions taking it by value may be difficult as C has to know the exact size of the structure. Not that it is that common with opaque pointers, I believe.
Ok, as i commented in the accepted answer that I couldn't use that approach, I ended up doing something like this for other's to comment on:
The backend rust code that gets compiled to rlib:
pub trait TestTrait {
fn trait_func(&mut self) -> i32;
}
pub struct TestStruct {
value: i32,
}
impl TestStruct {
pub fn new(value: i32) -> TestStruct {
TestStruct {
value: value,
}
}
pub fn decrement(&mut self, delta: i32) {
self.value -= delta;
}
}
impl TestTrait for TestStruct {
fn trait_func(&mut self) -> i32 {
self.value += 3;
self.value
}
}
The rust-wrapper over this that links to the above rlib and compiles into staticlib (ie., .a in Linux etc):
#[no_mangle]
pub extern fn free_function_wrapper(value: i32) -> i32 {
rustlib::free_function(value)
}
#[no_mangle]
pub extern fn new_test_struct_wrapper(value: i32) -> *mut libc::c_void {
let obj = rustlib::TestStruct::new(value);
unsafe {
let raw_ptr = libc::malloc(mem::size_of::<rustlib::TestStruct>() as libc::size_t) as *mut rustlib::TestStruct;
ptr::write(&mut *raw_ptr, obj);
raw_ptr as *mut libc::c_void
}
}
#[no_mangle]
pub extern fn test_struct_decrement_wrapper(raw_ptr: *mut libc::c_void, delta: i32) {
unsafe {
mem::transmute::<*mut libc::c_void, &mut rustlib::TestStruct>(raw_ptr).decrement(delta);
}
}
#[no_mangle]
pub extern fn test_struct_trait_function_wrapper(raw_ptr: *mut libc::c_void) -> i32 {
unsafe {
mem::transmute::<*mut libc::c_void, &mut rustlib::TestStruct>(raw_ptr).trait_func()
}
}
The C-wrapper (api.h & api.c) that links to the staticlib above and compiles into a shared object if required:
extern int32_t free_function_wrapper(int32_t value);
extern void* new_test_struct_wrapper(int32_t value);
extern void test_struct_decrement_wrapper(void* ptr, int32_t delta);
extern int32_t test_struct_trait_function_wrapper(void* ptr);
int32_t free_function(int32_t value) {
return free_function_wrapper(value);
}
void* new_test_struct(int32_t value) {
return new_test_struct_wrapper(value);
}
void test_struct_decrement(void* ptr, int32_t value) {
test_struct_decrement_wrapper(ptr, value);
}
int32_t test_struct_trait_function(void* ptr) {
return test_struct_trait_function_wrapper(ptr);
}
Now just run SWIG over the C file (i've posted just the .c file - you can guess the .h over which SWIG will run) for the target language, get an interface_wrap.c generated (default name) by it and compile these source code link, them against the staticlib to get a shared-object.
Eg, for python:
swig -python interface.i
gcc -std=c99 -c -fPIC -Wall -Werror -O2 api.c interface_wrap.c -I/usr/include/python2.7
gcc -shared -o _port_sample.so api.o interface_wrap.o -L./ -lrust_wrapper
Now just call from Python and the whole thing works:
$ python
Python 2.7.6 (default, Mar 22 2014, 22:59:56)
[GCC 4.8.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import port_sample
>>> handle = port_sample.new_test_struct(36)
>>> port_sample.test_struct_decrement(handle, 12)
>>> value = port_sample.test_struct_trait_function(handle)
>>> print value
27
>>> exit()
I hope someone finds this useful and/or can suggest improvements etc. I've also got this thing working and committed to my github repo: https://github.com/ustulation/rust-ffi/tree/master/python-swig-rust
Related
I've got a project that builds for ios, android and wasm targets, when I build for ios and android everything works but when I build for wasm I get the following error;
Im unsure what this error message actually means, I'm using an external crate libc, here's the code from my src/string.rs file
use libc::size_t;
// Helper struct that is used to give strings to C.
#[repr(C)]
pub struct StringPtr {
pub ptr: *const u8,
pub len: size_t,
}
impl<'a> From<&'a str> for StringPtr {
fn from(s: &'a str) -> Self {
StringPtr {
ptr: s.as_ptr(),
len: s.len() as size_t,
}
}
}
impl StringPtr {
pub fn as_str(&self) -> &str {
use std::{slice, str};
unsafe {
let slice = slice::from_raw_parts(self.ptr, self.len);
str::from_utf8(slice).unwrap()
}
}
}
and inside my lib.rs file I've got the following to import my string.rs file
extern crate libc;
mod string;
use string::StringPtr;
It's also worth noting that I am using cfg to conditionally include different code for different targets, maybe this is part of the problem?
I'm trying to create and return a C++ struct. I am currently getting a cannot move out of dereference of raw pointer error when I try to compile. Any idea how I can make this work?
#![allow(non_snake_case)]
#![allow(unused_variables)]
extern crate octh;
// https://thefullsnack.com/en/string-ffi-rust.html
use std::ffi::CString;
#[no_mangle]
pub unsafe extern "C" fn Ghelloworld(
shl: *const octh::root::octave::dynamic_library,
relative: bool,
) -> *mut octh::root::octave_dld_function {
let name = CString::new("helloworld").unwrap();
let pname = name.as_ptr() as *const octh::root::std::string;
std::mem::forget(pname);
let doc = CString::new("Hello World Help String").unwrap();
let pdoc = doc.as_ptr() as *const octh::root::std::string;
std::mem::forget(pdoc);
return octh::root::octave_dld_function_create(Some(Fhelloworld), shl, pname, pdoc);
}
pub unsafe extern "C" fn Fhelloworld(
args: *const octh::root::octave_value_list,
nargout: ::std::os::raw::c_int,
) -> octh::root::octave_value_list {
let list: *mut octh::root::octave_value_list = ::std::ptr::null_mut();
octh::root::octave_value_list_new(list);
std::mem::forget(list);
return *list;
}
I'm trying to create and return a C++ struct
You cannot; C++ (like Rust) does not have a stable, defined ABI. There is no way in Rust to specify that a structure has repr(C++), therefore you cannot create such a structure, much less return it.
The only stable ABI is the one presented by C. You can define structs as repr(C) to be able to return them directly:
extern crate libc;
use std::ptr;
#[repr(C)]
pub struct ValueList {
id: libc::int32_t,
}
#[no_mangle]
pub extern "C" fn hello_world() -> ValueList {
let list_ptr = ::std::ptr::null_mut();
// untested, will cause segfault unless list_ptr is set
unsafe { ptr::read(list_ptr) }
}
That method is highly suspicious though; normally you'd see it as
#[no_mangle]
pub extern "C" fn hello_world() -> ValueList {
unsafe {
let mut list = mem::uninitialized();
list_initialize(&mut list);
list
}
}
See also:
Is it possible to use a C++ library from Rust when the library uses templates (generics)?
I encourage you to read my Rust FFI Omnibus.
Given a struct:
#[repr(C)]
pub struct User {
pub name: *const c_char,
pub age: u8,
pub ctx: ??,
}
the field ctx would only be manipulated by C code; it's a pointer to a C struct UserAttr.
According to the Rust FFI documentation, the choice would be defined as an opaque type pub enum UserAttr {}. However, I found that Rust is unable to copy its value, e.g. why does the address of an object change across methods.
What's the right way in Rust to define such an opaque pointer, so that its value (as a pointer) gets copied across methods?
The future
RFC 1861 introduced the concept of an extern type. While implemented, it is not yet stabilized. Once it is, it will become the preferred implementation:
#![feature(extern_types)]
extern "C" {
type Foo;
}
type FooPtr = *mut Foo;
Today
The documentation states:
To do this in Rust, let’s create our own opaque types:
#[repr(C)] pub struct Foo { private: [u8; 0] }
#[repr(C)] pub struct Bar { private: [u8; 0] }
extern "C" {
pub fn foo(arg: *mut Foo);
pub fn bar(arg: *mut Bar);
}
By including a private field and no constructor, we create an opaque
type that we can’t instantiate outside of this module. An empty array
is both zero-size and compatible with #[repr(C)]. But because our
Foo and Bar types are different, we’ll get type safety between the
two of them, so we cannot accidentally pass a pointer to Foo to
bar().
An opaque pointer is created such that there's no normal way of creating such a type; you can only create pointers to it.
mod ffi {
use std::ptr;
pub struct MyTypeFromC { _private: [u8; 0] }
pub fn constructor() -> *mut MyTypeFromC {
ptr::null_mut()
}
pub fn something(_thing: *mut MyTypeFromC) {
println!("Doing a thing");
}
}
use ffi::*;
struct MyRustType {
score: u8,
the_c_thing: *mut MyTypeFromC,
}
impl MyRustType {
fn new() -> MyRustType {
MyRustType {
score: 42,
the_c_thing: constructor(),
}
}
fn something(&mut self) {
println!("My score is {}", self.score);
ffi::something(self.the_c_thing);
self.score += 1;
}
}
fn main() {
let mut my_thing = MyRustType::new();
my_thing.something();
}
Breaking it down a bit:
// opaque -----V~~~~~~~~~V
*mut MyTypeFromC
// ^~~^ ------------ pointer
Thus it's an opaque pointer. Moving the struct MyRustType will not change the value of the pointer.
The past
Previous iterations of this answer and the documentation suggested using an empty enum (enum MyTypeFromC {}). An enum with no variants is semantically equivalent to the never type (!), which is a type that cannot exist. There were concerns that using such a construct could lead to undefined behavior, so moving to an empty array was deemed safer.
Suppose I have the following Rust library:
// lib.rs
#![crate_type = staticlib]
#[no_mangle]
pub extern fn do_something(number: i32) {
// something
}
#[no_mangle]
pub extern fn do_something_else(collection: &Vec<i32>) {
// something
}
I know that, to call do_something from C, I'd just need to declare an extern function taking an int32_t, but is it possible to call do_something_else? If so, how?
You can, but the better question is should you?
Since you cannot construct a Vec from C, you'd have to construct it in Rust and then return a pointer to C. C code would own the pointer to the Vec and would then pass it back when calling do_something_else.
Then there's the problem that you can't really modify the Vec in C either, other than by creating new FFI methods that mirror all of the Rust methods.
You also probably shouldn't take a &Vec<i32> because Rust references are guaranteed to not be NULL, and there's nothing that enforces that when called from C. It's better to take a *const Vec<i32>, assert that it's non-NULL and convert it to a reference.
Chances are that you want to accept a C array through the FFI boundary. C arrays are a pointer and a length, so you'd accept both and reconstitute a Rust slice (since you wouldn't own the array):
use std::slice;
pub extern fn do_something_else(p: *const i32, len: libc::size_t) {
let slice = unsafe {
assert!(!p.is_null());
slice::from_raw_parts(p, len)
};
}
Obligatory link to The Rust FFI Omnibus.
If you really needed to do what you asked, it would probably look something like this:
extern crate libc;
#[no_mangle]
pub extern fn make_vec() -> *mut Vec<i32> {
Box::into_raw(Box::new(Vec::new()))
}
#[no_mangle]
pub extern fn add_number(vec: *mut Vec<i32>, val: libc::int32_t) {
let vec = unsafe {
assert!(!vec.is_null());
&mut *vec
};
vec.push(val);
}
#[no_mangle]
pub extern fn print_vec(vec: *const Vec<i32>) {
let vec = unsafe {
assert!(!vec.is_null());
&*vec
};
println!("{:?}", vec);
}
#[no_mangle]
pub extern fn drop_vec(vec: *mut Vec<i32>) {
unsafe {
assert!(!vec.is_null());
Box::from_raw(vec);
}
}
And would be used like (untested):
// Add extern declarations
int main(int argc, char *argv[]) {
void *v = make_vec(); // Use a real typedef here
add_number(v, 42);
print_vec(v);
drop_vec(v);
}
You'd want to run this under valgrind to make sure I didn't do anything stupid memory-wise.
I have some c functions with a struct pointer argument.
extern "C" {
fn InitSomeStruct() -> *SomeStruct;
fn SomeFunction(v: *SomeStruct);
fn DestroySomeStruct(v: *SomeStruct);
}
fn main() {
unsafe {
let s = InitSomeStruct();
SomeFunction(s);
DestroySomeStruct(s);
}
}
The implementation of SomeStruct is unknown.
How to declare and use external struct like SomeStruct from the rust code?
The convention is to use an empty enum for opaque FFI types, that is:
enum SomeStruct {}
An empty struct like struct SomeStruct; is also used sometimes.