Building an iOS App in Rust, Part 3: Passing Owned Objects between Rust and iOS

Editor’s note: This is the third post in our series on building an iOS app in Rust.

Welcome to Part 3 of our “Building an iOS App in Rust” series. This post continues to build on the tools and details we set up in Part 1 and Part 2, so please refer back to those as needed. Part 1 walks you through setting up a cross-compiler built from the latest “unstable” Rust compiler. The code in in this post uses a feature that was only recently stabilized, so if you are following along with your own compiler toolchain, note that you’ll need Rust 1.4 or newer.

Another major change is that we’re now using Swift 2, which added the capability to pass Swift functions to C APIs that wanted function pointers. We no longer need to drop down into Objective-C to wrap our Rust code.

In Part 2, we ended with passing strings between Rust and Swift. Our implementation worked but was not ideal in either direction:

• When passing a Swift String into Rust via the c_string_to_rust function, the pointer we give to Rust is only valid for the duration of the function call. If we want to keep the string to do something with it later, we’d need to make a copy of the string data.
• When passing a Rust string to Swift as we did in the get_string_from_rust function, the pointer we returned was valid only because it pointed to static constant data. We don’t currently have a way to pass a dynamically allocated string from Rust to Swift.

Both of these issues would be complete showstoppers for a real application. We need a way to pass much more complex data than strings, and we’ll need to be able to correctly and safely manage the ownership of that data.

As in Part 2, we will not be going over every line of code in detail, but all of the code for this post is available on GitHub.

Ownership in Rust

Rust is a great language for a number of reasons, but the one feature where it really shines is how it deals with ownership (who is responsible for allocating and deallocating resources held by an instance) and borrowing (loaning out temporary access to an instance without giving away ownership. Much has been written about this, with more detail than I can offer here. If you want to learn more, check out the excellent Fearless Concurrency with Rust blog post as well as the Rust book’s sections on Ownership, References and Borrowing and Lifetimes.

In pure Rust, the compiler makes sure you obey ownership rules that ensure all resources will be cleaned up at the proper time. The same ownership rules provide thread safety guarantees that we’ll discuss in a later post. When we’re working with the foreign function interface (FFI) layer, we have to be much more careful, as we’re interacting with a system outside of the Rust compiler’s knowledge, so we don’t get nearly as much help.

The most basic things we want to be able to understand are (a) how long will an object we’re passing between languages be valid (e.g., in c_string_to_rust, the pointer is valid only for the function call), and (b) who is responsible for cleaning it up (e.g., in c_string_to_rust, Swift will free the string’s memory). For the rest of this post, we’re going to look at how to pass ownership of an object across the boundary: creating an object in Rust and giving responsibility for its cleanup to Swift and vice versa.

Giving Ownership of a Rust Instance to Swift

Most of the Rust types we’re going to create will not boil down to a primitive or even a simple structure like RustByteSlice. For example, we could build a Rust structure like this, which represents a label and some associated data:

// Automatically derive an implementation of the `Debug` trait so we can
// print instances of NamedData for debugging purposes.
#[derive(Debug)]
pub struct NamedData {
    name: String,
    data: Vec<i32>,
}

When we wrote the C header file for RustByteSlice, we put the C-compatible definition of RustByteSlice directly in the header. We can’t do that here, though: we don’t know what the in-memory layout of NamedData is, because we don’t know what the internal data layouts of String or Vec<i32> are (nor should we need to). If we want to create instances of this type and give them to Swift, we can create a C interface for creation and destruction like this:

// Forward declare a struct but never specify its fields.
// We will only work with pointers to named_data.
struct named_data;

// Create a new instance of `named_data`.
// The caller is responsible for passing the returned pointer to
// named_data_destroy, or memory will be leaked.
struct named_data *named_data_new(void);

// Free a `named_data` instance returned by `named_data_new`.
void named_data_destroy(struct named_data *data);

The Swift side can’t use a struct named_data * directly; its bridged type, COpaquePointer, makes that obvious. We’ll need to add functions to access the properties we want to expose:

// Get the name of a `named_data`. The returned byte slice is valid until
// the `named_data` instance is destroyed.
struct RustByteSlice named_data_get_name(const struct named_data *data);

// Get the number of elements stored in `data`.
size_t named_data_count(const struct named_data *data);

On the Rust side, let’s start by implementing the Drop trait for NamedInit. The drop function is called when a value goes out of scope; it’s analogous to a destructor in C++ or deinit in Swift (although any value in Rust can implement Drop, whereas there’s no way to have a deinit for Swift structs or enums). We don’t actually need to do anything, but we can add a print statement for our own understanding:

impl Drop for NamedData {
    fn drop(&mut self) {
        println!("{:?} is being deallocated", self);
    }
}

To implement named_data_new, we need to create an instance of NamedData on the heap (if we created it on the stack, it would be destroyed as soon as named_data_new returns), then return a raw pointer to the instance. Rust’s standard library provides the Box type for heap-allocating instances. Typically Rust’s RAII semantics would cause a Box-allocated instance to be deallocated when the box goes out of scope, but we can use Box::into_raw to cause the instance to be forgotten by the RAII system.

#[no_mangle]
pub extern fn named_data_new() -> *mut NamedData {
    // Create an instance of NamedData.
    let named_data = NamedData{
        name: "some data".to_string(),
        data: vec![1, 2, 3, 4, 5],
    };

    // Put named_data into a Box, which moves it onto the heap.
    let boxed_data = Box::new(named_data);

    // Convert our Box<NamedData> into a *mut NamedData. Rust is no longer
    // managing the destruction of boxed_data; we must (at some point in the
    // future) convert this pointer back into a Box<NamedData> so it can be
    // deallocated.
    Box::into_raw(boxed_data)
}

This will leak memory if we don’t later give the instance back to a Rust Box for deallocation, but that’s exactly what we want! We created a heap-allocated NamedData, got a pointer to it that we can give to Swift, and Rust will not deallocate it out from under us. We can implement named_data_destroy that will take a raw pointer to a NamedData, put it back into a Box, and let that Box fall out of scope, causing the instance to be deallocated.

#[no_mangle]
pub unsafe extern fn named_data_destroy(data: *mut NamedData) {
    // Convert a *mut NamedData back into a Box<NamedData>.
    // This function is unsafe because the Rust compiler can't know
    // whether data is actually pointing to a boxed NamedData.
    //
    // Note that we don't actually have to do anything else or even
    // give the new Box a name - when we convert it back to a Box
    // and then don't use it, the Rust compiler will insert the
    // necessary code to drop it (deallocating the memory).
    let _ = Box::from_raw(data);
}

Implementing the two accessor functions is simpler; the only new bit here is converting a raw *const NamedData into a Rust reference (&NamedData), which requires an unsafe block (because we have to dereference the pointer, and the Rust compiler can’t know whether the pointer is actually valid):

#[no_mangle]
pub extern fn named_data_get_name(named_data: *const NamedData) -> RustByteSlice {
    let named_data = unsafe { &*named_data };
    RustByteSlice::from(named_data.name.as_ref())
}

#[no_mangle]
pub extern fn named_data_count(named_data: *const NamedData) -> size_t {
    let named_data = unsafe { &*named_data };
    named_data.data.len() as size_t
}

There is an interesting point to make here about the use of unsafe. The Rust compiler is extremely strict about safety, but it is sometimes necessary to use unsafe to implement particular details. We should be careful what kind of API we present, though. These functions are primarily intended to be used from outside of Rust, but they could still be called by other Rust code. These functions appear to the Rust compiler to be safe - it should be memory safe to call these with any possible *const NamedData. But our implementation does not check for NULL, in particular. This is very bad - we have an unsafe function masquerading as a safe one. To fix this, we can move unsafe up from just a block around the pointer dereference to a marker on the entire function:

#[no_mangle]
pub unsafe extern fn named_data_get_name(named_data: *const NamedData) -> RustByteSlice {
    let named_data = &*named_data;
    RustByteSlice::from(named_data.name.as_ref())
}

#[no_mangle]
pub unsafe extern fn named_data_count(named_data: *const NamedData) -> size_t {
    let named_data = &*named_data;
    named_data.data.len() as size_t
}

Now our functions are correctly marked for other Rust consumers - if they want to call these functions, they can only do so from other unsafe code. We also make use of a fairly common Rust idiom: let named_data = &*named_data; creates a new binding for the named_data name which shadows the old named_data. The new named_data has type &NamedData; the shadowed one that we no longer can (or need to) access had type *const NamedData.

On the Swift side, we want to guarantee we’re not going to forget to pair every call to named_data_new with a call to named_data_destroy, so we’ll create a RustNamedData wrapper class with an appropriate deinit. This is also a convenient place to put calls to the other accessor functions, as well:

class RustNamedData {
    private let raw: COpaquePointer

    init() {
        raw = named_data_new()
    }

    deinit {
        named_data_destroy(raw)
    }

    var name: String {
        let byteSlice = named_data_get_name(raw)
        return byteSlice.asString()!
    }

    var count: Int {
        return named_data_count(raw)
    }
}

We can create an instance of this class, print some properties, and see the destruction happen as we expect:

let namedData = RustNamedData()
print("namedData.name = \(namedData.name)")
print("namedData.count = \(namedData.count)")

// Output from running the above snippet:
// namedData.name = some data
// namedData.count = 5
// NamedData { name: "some data", data: [1, 2, 3, 4, 5] } is being deallocated

Embedding Rust into another language is relatively straightforward. There are no concerns about any runtime support like a garbage collector, so we just have to give the host language (Swift) a way to create and destroy instances. Going the other direction is a little trickier thanks to ARC.

Giving Ownership of a Swift Instance to Rust

Passing ownership of Swift objects down to Rust is problematic. We saw earlier how to pass an ephemeral pointer to a String; we could easily do that with other Swift types by making use of the withUnsafePointer Swift function. However, pointers created by withUnsafePointer are only valid for the duration of that function call, and we’re going to need a way to give Rust a more permanent handle on Swift objects. In Swift 1, we would need to drop down to Objective-C to solve this problem. Since Swift 2 added the ability to pass Swift functions to APIs expecting C function pointers, we no longer need to do that. We will still get our hands a little dirty, though.

Let’s start with the C interface each side is going to implement:

struct swift_object {
    void *user;
    void (*destroy)(void *user);
    void (*callback_with_int_arg)(void *user, int32_t arg);
};

void give_object_to_rust(struct swift_object object);

The swift_object struct has three fields:

1. user is a void *; it will be a pointer to an instance of our Swift object.
2. destroy is a C function pointer that will be called when Rust wants to destroy user.
3. callback_with_int_arg is a C function pointer that Rust can call with a 32-bit signed integer argument.

Let’s create the Swift side of our Swift object:

class SwiftObject {
    deinit {
        print("SwiftObject being deallocated")
    }

    private func callbackWithArg(arg: Int) {
        print("SwiftObject: received callback with arg \(arg)")
    }

    func sendToRust() {
        let ownedPointer = UnsafeMutablePointer<Void>(Unmanaged.passRetained(self).toOpaque())
        let wrapper = swift_object(
            user: ownedPointer,
            destroy: destroy,
            callback_with_int_arg: callback_with_int_arg)
        give_object_to_rust(wrapper)
    }
}

private func callback_with_int_arg(user: UnsafeMutablePointer<Void>, arg: Int32) {
    let obj: SwiftObject = Unmanaged.fromOpaque(COpaquePointer(user)).takeUnretainedValue()
    obj.callbackWithArg(Int(arg))
}

private func destroy(user: UnsafeMutablePointer<Void>) {
    let _ = Unmanaged<SwiftObject>.fromOpaque(COpaquePointer(user)).takeRetainedValue()
}

deinit and callbackWithArg are straightforward: we just want to see output when they’re called. Most of the magic happens in sendToRust, so let’s break that down:

let ownedPointer = UnsafeMutablePointer<Void>(Unmanaged.passRetained(self).toOpaque())

We have an instance of a Swift object (self), and the bridged form of our swift_object struct is expecting an UnsafeMutablePointer<Void> for its user field. We have to pass through two intermediate states to get there:

• Unmanaged is Swift’s window into you taking more control over memory management. When you call Unmanaged.passRetained(self), you get back “an unmanaged reference with an unbalanced retain”. This is exactly what we want: the reference has now been retained, and we are responsible for releasing the object when we (or Rust) is finished with it.
• Given an Unmanaged<SwiftObject>, we can call toOpaque() on it to get a COpaquePointer.
• Given a COpaquePointer, we can finally create an UnsafeMutablePointer, the type we need to supply for user.

Now that we’ve converted self into an UnsafeMutablePointer<Void>, we can build up an instance of the swift_object struct and call our give_object_to_rust function:

let wrapper = swift_object(
    user: ownedPointer,
    destroy: destroy,
    callback_with_int_arg: callback_with_int_arg)
give_object_to_rust(wrapper)

The destroy and callback_with_int_arg arguments are private functions; let’s look at those now.

callback_with_int_arg is given a user (the exact same UnsafeMutablePointer<Void> we just created and an integer argument. The tricky bit here is converting user back into a usable SwiftObject; we have to repeat the process we did above but in reverse:

// UnsafeMutablePointer<Void> -> COpaquePointer
COpaquePointer(user)

// COpaquePointer -> Unmanaged<SwiftObject>
Unmanaged.fromOpaque(COpaquePointer(user))

// Unmanaged<SwiftObject> -> SwiftObject
Unmanaged.fromOpaque(COpaquePointer(user)).takeUnretainedValue()

Note that we call takeUnretainedValue(), not takeRetainedValue(), because we do not want to modify the reference count of the underlying SwiftObject. Now that we have a SwiftObject, we can call methods on it just like normal:

obj.callbackWithArg(Int(arg))

Finally, destroy is a one-liner that is almost identical to the first line of callback_with_int_arg. The difference, as you probably expect, is that here we do call takeRetainedValue(). This will decrement the reference count on the underlying object, causing it to be deallocated (assuming Rust was holding the only or last reference to it).

Now that the Swift side is ready, what does the Rust side look like? First, let’s define the SwiftObject struct:

use libc::c_void;

#[repr(C)]
pub struct SwiftObject {
    user: *mut c_void,
    destroy: extern fn(user: *mut c_void),
    callback_with_int_arg: extern fn(user: *mut c_void, arg: i32),
}

This shouldn’t be too bad, if you’ve made it this far. C function pointers come in as extern fn types, and we need to make sure the argument and return types match. (If we wanted to allow these function pointers to be NULL, we would use Option<extern fn(…)> instead, but we don’t need to do that for this example.)

Now for give_object_to_rust. To make things interesting, we’ll start up a thread, move the SwiftObject onto that thread, sleep for 1 second, and then issue the callback into iOS. To tell Rust that it is safe for instances of SwiftObject to be sent across threads, we’ll also need to add an implementation of the (empty) Send trait. (The explanation for this is a little long, and this post is already too long by half, so I’ll refer you to the Rust book’s Concurrency chapter if you’re curious.)

use std::thread;

unsafe impl Send for SwiftObject {}

#[no_mangle]
pub extern fn give_object_to_rust(obj: SwiftObject) {
    println!("moving SwiftObject onto a new thread created by Rust");
    thread::spawn(move||{
        thread::sleep_ms(1000);
        (obj.callback_with_int_arg)(obj.user, 10);
        (obj.destroy)(obj.user);
    });
}

If we run this, we’ll find everything working; we get the following log, with a 1 second delay between the 2nd and 3rd lines:

moving SwiftObject onto a new thread created by Rust
SwiftObject: received callback with arg 10
SwiftObject being deallocated

You can also set a breakpoint in SwiftObject.callbackWithArg and see that the callback is happening off of the main thread.

However, there is the unsightly bit of having to manually call obj.destroy. This is Rust - we should not need to do manual resource management! Earlier, we implemented the Drop trait on NamedData. Let’s try to do the same thing here. We can move the call to destroy into drop, which means Rust will put the call at exactly the right place (whenever our SwiftObject falls out of scope):

impl Drop for SwiftObject {
    fn drop(&mut self) {
        (self.destroy)(self.user);
    }
}

#[no_mangle]
pub extern fn give_object_to_rust(obj: SwiftObject) {
    println!("moving SwiftObject onto a new thread created by Rust");
    thread::spawn(move||{
        thread::sleep_ms(1000);
        (obj.callback_with_int_arg)(obj.user, 10);
        /* (obj.destroy)(obj.user); */
    });
}

This compiles, but with a pretty scary warning:

src/swift_ownership_to_rust.rs:13:1: 17:2 warning: implementing Drop adds hidden state to types, possibly conflicting with `#[repr(C)]`, #[warn(drop_with_repr_extern)] on by default
src/swift_ownership_to_rust.rs:13 impl Drop for SwiftObject {
src/swift_ownership_to_rust.rs:14     fn drop(&mut self) {
src/swift_ownership_to_rust.rs:15         (self.destroy)(self.user);
src/swift_ownership_to_rust.rs:16     }
src/swift_ownership_to_rust.rs:17 }

It turns out the warning is scary-sounding for a reason: running this code now crashes!

Explaining what’s going on is a little involved, but I’ll try to summarize. Currently, when you implement Drop on a struct, the Rust compiler inserts a hidden field into that struct that it uses to track whether or not it needs to call drop. This is just a limitation of the current implementation; there are an accepted RFC and an open issue that will address this. For now, however, this hidden field changes the size of SwiftObject. The Rust compiler is warning us that we said we wanted an in-memory representation compatible with C, but that isn’t happening because of this hidden field.

Luckily, fixing this is easy. We can wrap SwiftObject up in a new Rust type and implement Drop on that type instead. We’ll use Rust’s newtype syntax for a struct-that-only-exists-to-wrap-another-type:

use std::ops::Deref;

struct SwiftObjectWrapper(SwiftObject);

impl Deref for SwiftObjectWrapper {
    type Target = SwiftObject;

    fn deref(&self) -> &SwiftObject {
        &self.0
    }
}

impl Drop for SwiftObjectWrapper {
    fn drop(&mut self) {
        (self.destroy)(self.user);
    }
}

There’s another new thing here: we implemented the Deref trait. This lets us freely access the fields (and methods, if there were any) on a SwiftObjectWrapper’s inner SwiftObject. Finally, we need to update our give_object_to_rust implementation to wrap the struct Swift gives us into a SwiftObjectWrapper, and move that wrapper onto the background thread:

#[no_mangle]
pub extern fn give_object_to_rust(obj: SwiftObject) {
    println!("moving SwiftObject onto a new thread created by Rust");
    let obj = SwiftObjectWrapper(obj);
    thread::spawn(move||{
        thread::sleep_ms(1000);
        (obj.callback_with_int_arg)(obj.user, 10);
    });
}

This compiles (and runs) without warning or error, and we no long have to worry about calling destroy: Rust will insert the call for us at precisely the right moment.

Next Steps

We’ve covered a lot in this post! We now know how to pass all kinds of things from Rust to Swift and from Swift to Rust. In the next couple of posts, we’ll start to take steps towards a more realistic example and explore two different ways to implement view models in Rust that can be used from Swift.

All the code, plus the extra stuff necessary to get it running (like an Xcode project file), is available on GitHub.