closes #25 closes #30 Fixes #32 I seem to prefer generators. Here are what benefits I see.

1. StopIteration is automatically raised when Primes stops yielding
2. Only one value is passed back at a time (memory savings)

    def __iter__(self):
        running = True
        while running:
            prime = self.next()
            yield prime
            running = prime != 0

Is there any reason to yield 0? I think, it was intended to indicate the end of sequence.

Working toward #8

• Reworded sentences to not be in the first person.
• Fixed a typo in the bindgen intro.
• Major rewrite of what the build.rs script does and when.

Bits and pieces of this book were written in the first person, while others have been written in the third person. To the book more consistent and easier for others to contribute to, all usage of the first person point-of-view should be converted to third person.

The easiest way to find what to fix is to grep all markdown files for common first person phrases (like " I ").

(Hint: grep -E " I | I'm | me | my " $(find . -name '*.md'))

Progress so far:

• [x] README
• [x] Introduction
• [x] Arrays
• [x] Structs
• [x] Strings
• [x] Bindgen
• [x] Pythonic One instance left.
• [x] Dynamic Loading
• [x] Callbacks
• [x] Best Practices One instance left.

~~I'm not sure if I'm on the right place for this:~~ https://michael-f-bryan.github.io/rust-ffi-guide/fun/problems.html ~~All your examples have the following code inside:~~

# #![allow(unused_variables)]
#fn main() {

~~This won't ever compile as # is not a correct comment char in rust. Please correct it to // or /* or leave this part out.~~

error: expected `[`, found `#`
 --> adder.rs:2:3
  |
2 | # #![allow(unused_variables)]
  |   ^

error: aborting due to previous error(s)

I'm sorry, seems like without both JS CDN's I'm seeing some code to parse.

And the first example uses "uit" not "uint", unknown type.

Working toward #8 Each pull request will focus on one file.

Reworded some more sentences. Although, in some cases I reworded a paragraph to reduce the amount of "you", or to make a sentence more straightforward.

This is a revised tutorial written from the perspective of someone wanting to create a basic REST client which uses Qt for the GUI and Rust for the business logic.

(rendered)

(fixes #40)

This introduces a more organised scheme for building and testing the example code. Each chapter has its own Makefile which must define the following three rules: build, test, and clean. Allowing you to run make test in the top level directory and have make test be run in each chapter.

It also adds cargo workspaces so that the examples can share build artefacts instead of unnecessarily rebuilding common crates like libc half a dozen times.

cc: #29

Partial patch set for #8 So, I divided up the commits into little pieces in case anything seems off. Also, thanks for the existing book text!

Comments?

I was glad to find your article and applied it in my project. However, this does not work when passing structures around dynamic libraries.

For now, it sounds to me that the use case is only for foreign languages with only canonical structures around that.

See https://github.com/rust-lang/rust/issues/67179 and so https://github.com/rust-lang/rust/pull/63338 with this https://github.com/rust-lang/rust/pull/63338#issuecomment-519122090

Do you have any workaround for this, please ? Thanks!

As part of supporting multiple versions of LLVM in inkwell, I ran into a case where perfectly valid input to a certain function for non existent data (similar to looking up a key that doesn't exist in a hash table) would cause a segfault in a small subset of versions of LLVM. This is presumably a LLVM bug since it works fine in previous versions.

Thinking about this, I'm wondering: How terrible of an idea is it to set up a signal handler(IE via the signal crate) to catch that segfault and return the error case that I would have normally returned in LLVM versions that don't segfault?

I'm thinking at best the segfault could just be a null pointer dereference, but in the worst case it could have done something crazy like corrupted the whole stack...

Is this a crazy idea? What if I first look at the LLVM source code and am able to verify that the bug(maybe there's a fix I can look at in a newer version)'s segfault is relatively harmless in each offending version (ie null ptr deref or reading (but not writing) to invalid memory?).

According to your own article (I believe), ABI for dyn Trait objects is unstable, therefore the following use in this guide might be UB:

#[macro_export]
macro_rules! declare_plugin {
    ($plugin_type:ty, $constructor:path) => {
        #[no_mangle]
        pub extern "C" fn _plugin_create() -> *mut $crate::Plugin {
            // make sure the constructor is the correct type.
            let constructor: fn() -> $plugin_type = $constructor;

            let object = constructor();
            let boxed: Box<$crate::Plugin> = Box::new(object);
            Box::into_raw(boxed)
        }
    };
}

Note the use of *mut $crate::Plugin as the return type. In Rust 2018/2021, it should be *mut dyn $crate::Plugin because Plugin is a trait (instead of a type). And if the layout of trait objects were to change for building the plugin and the host program (though I doubt if this would ever happen), this would result in UB.

For solutions, it seems that abi_stable::sabi_trait could be a candidate, but it looks ad-hoc and pulls in a non-trivial amount of dependencies. Another way would be to just use the "manual vtable" approach mentioned in your blog, which requires some boilerplate, but looks good otherwise.

The chapter gives this example of loading a plugin:

pub unsafe fn load_plugin<P: AsRef<OsStr>>(&mut self, filename: P) -> Result<()> {
    type PluginCreate = unsafe fn() -> *mut Plugin;

    let lib = Library::new(filename.as_ref()).chain_err(|| "Unable to load the plugin")?;

    // We need to keep the library around otherwise our plugin's vtable will
    // point to garbage. We do this little dance to make sure the library
    // doesn't end up getting moved.
    self.loaded_libraries.push(lib);

    let lib = self.loaded_libraries.last().unwrap();

    let constructor: Symbol<PluginCreate> = lib.get(b"_plugin_create")
        .chain_err(|| "The `_plugin_create` symbol wasn't found.")?;
    let boxed_raw = constructor();

    let plugin = Box::from_raw(boxed_raw);
    debug!("Loaded plugin: {}", plugin.name());
    plugin.on_plugin_load();
    self.plugins.push(plugin);


    Ok(())
}

However (in my testing, which has only been on Windows 10), this code crashes unless I change the type alias to:

type PluginCreate = unsafe extern "C" fn() -> *mut Plugin;

With the addition of extern "C", everything appears to work correctly.

It's been a while since I last updated the guide and I've learned a lot since then. I think it may be a good idea to start over and take a slightly different approach.

I think we may want to break things into two parts. In the first part we'll address common patterns and techniques used when writing FFI code, with the second part being a worked example (or two?) that lets us show off these techniques.

Progress so far (rendered)

Concepts and Patterns:

• [x] Calling basic functions and linking (#[no_mangle], extern fn ... and all that) (#66)
• [x] Passing around reference types (&[u8], char*, etc) (#69)
• [x] Binding to complex objects (#70)
• [ ] Ownership and memory safety (e.g. who should call free and what happens if you free from the wrong allocator)
• [x] Callbacks and function pointers
• [ ] Proper error handling
• [ ] Best practices for API design
• [ ] Starting a task in the background
• [ ] Exception safety
• [x] Dynamic loading and plugins (dlopen/LoadLibrary) (#71)
• [x] Fun with build systems (e.g. build a Rust crate using cmake)
• [ ] Bindings
  • [ ] Writing a C++ wrapper class for a Rust type

Ideas for worked examples:

• [x] Write a Rust wrapper for a common C library (#67)
• [ ] Use a Rust crate as part of a Qt (C++) application (e.g. use reqwest to do HTTP requests in the background)
• [ ] Using a Rust library to speed up a Python application
• [ ] Embedding Node.JS in a Rust application so we can call some javascript stuff

Note: All PRs should be made against the reboot branch (#65) so we don't overwrite the existing guide until the new version is ready.

This problem would pass a normal Rust enum to C++, where the C++ code has declared a tagged union which roughly matches how Rust does things internally.

The solution should mention that this is UB because an enum's internal representation is unspecified. Instead Rust should manually define a tagged union which is the equivalent of our enum, possibly adding the appropriate From<...> impls.

You'd need to explicitly write something like this:

#[derive(Copy, Clone)]
#[repr(C)]
struct Car {
    tag: CarType,
    value: CarValue,
}

#[derive(Copy, Clone)]
#[repr(C)]
union CarValue {
    fast: FastCar,
    slow: SlowCar,
}

#[derive(Copy, Clone, Debug)]
struct FastCar(u32);

#[derive(Copy, Clone, Debug)]
struct SlowCar(f64);

#[derive(Copy, Clone)]
#[repr(C)]
enum CarType {
    Fast,
    Slow,
}

As well as its C equivalent:

struct SlowCar{
  ...
}

struct FastCar{
  ...
}

union union_car {
  FastCar,
  SlowCar
}

enum Cartype{Slow,Fast};

struct Car{
  union_car inner;
  Cartype tag;
} 

When eg. you get a buffer allocated from the C side of the FFI and are expected to manage its lifetime in Rust, extra care needs to happen in the Rust code to deallocate with the C malloc/free and not just drop it since Rust is using jemalloc.

The same precautions need to be taken when handing buffers to the C side.

I've found it needed to write small custom functions to expose deallocation or allocation missing on the C side to make that clear and correct.