Rust bindings built on top of the C bindings

[neilisaac]

Hi, as I alluded to in eclipse-iceoryx/iceoryx-rs#1, I'm working on Rust bindings for IceOryx using bindgen rather than rust-cpp.

This design provides RAII struct wrappers for each object, but is conceptually 1:1 with the C bindings to make it easy to understand.

It uses a "-sys" crate containing the bindings generated by bindgen for compatibility with cargo as well as other builds systems (bazel with rules_rust in particular).

Here is a working example of these Rust bindings. My bindings currently support almost all IceOryx v1 C functions.

To give an idea of the API, here are the publisher functions:

pub struct Publisher(sys::iox_pub_t, Pin<Box<sys::iox_pub_storage_t>>);

impl Publisher {
    pub fn new(service: &str, instance: &str, event: &str, opts: PubOptions) -> Self {
        ...
        let mut data = Box::pin(Default::default());
        let pointer = unsafe {
            sys::iox_pub_init(
                &mut *data,
                service.as_ptr(),
                instance.as_ptr(),
                event.as_ptr(),
                &opts.options,
            )
        };
        Self(pointer, data)
    }

    pub fn loan_chunk(&self, size: usize) -> Result<PubChunkHandle, AllocationError> {
        let mut data = std::ptr::null_mut();
        AllocationError::new_result(unsafe {
            sys::iox_pub_loan_chunk(
                self.0,
                &mut data,
                size as u32,
            )
        })?;
        Ok(PubChunkHandle {
            data,
            sent: false,
            publisher: self,
            size,
        })
    }

    pub fn offer(&mut self) { unsafe { sys::iox_pub_offer(self.0) } }
    pub fn stop_offer(&mut self) { ... }
    pub fn is_offered(&mut self) -> bool { ... }
    pub fn has_subscribers(&self) -> bool { ... }
    pub fn iox_pub_get_service_description(&self) -> ServiceDescription { ... }
}

impl Drop for Publisher {
    fn drop(&mut self) { unsafe { sys::iox_pub_deinit(self.0) } }
}

pub struct PubChunkHandle<'a> {
    data: *mut ffi::c_void,
    publisher: &'a Publisher,
    sent: bool,
    size: usize,
}

impl PubChunkHandle<'_> {
    /// Send the data via the associated Publisher
    pub fn publish(mut self) {
        unsafe { sys::iox_pub_publish_chunk(self.publisher.0, self.data) };
        self.sent = true;
    }

    /// Safe interface to write into a shared memory chunk.
    pub fn as_uninit_slice(&mut self) -> &mut UninitSlice {
        unsafe { UninitSlice::from_raw_parts_mut(self.data.cast(), self.size) }
    }

    /// Expose the payload portion of the chunk as a mutable byte slice.
    /// This can be written to conveniently using bytes::BufMut.
    /// # Safety
    /// Despite this function not being marked as unsafe, the data returned by as_slice is uninitialized.
    pub fn as_slice(&mut self) -> &mut [u8] {
        unsafe { std::slice::from_raw_parts_mut(self.data.cast(), self.size) }
    }

    /// Cast the chunk to a given type T.
    /// This may be useful with a #[repr(C)] type for example.
    /// # Safety
    /// This function is marked as unsafe because it is the caller's responsibility
    /// to ensure that T can safely be written into the chunk.
    /// T must fit in the allocated chunk and must not reference data outside the chunk (ex. via pointers/references)
    pub unsafe fn as_uninitialized<T>(&mut self) -> &mut std::mem::MaybeUninit<T> {
        &mut *self.data.cast()
    }
}

impl Drop for PubChunkHandle<'_> {
    fn drop(&mut self) {
        if !self.sent {
            unsafe { sys::iox_pub_release_chunk(self.publisher.0, self.data) }
        }
    }
}

For the Listener callbacks, I'm storing boxed closures to share thread-safe state with the callbacks.

WaitSet and UserTrigger are mostly 1:1 with the C API. It writes into a NotificationBuffer which is backed by a fixed-capacity vec and exposes an iterator to consume NotificationInfo (a trivial wrapper around iox_notification_info_t).

I would welcome any comments or potential issues you see, and would consider open-sourcing this work if there's interest from the core developers. If there's still more interest in building directly off the C++ API, I totally understand and am happy to at least share ideas/learnings.

[elBoberido]

@neilisaac I would be happy to combine the effort for idiomatic rust bindings. I've chosen a different approach with the cpp crate. This was mainly because of two reasons. There is an additional indirection with the C binding and they are also not complete (no API for the introspection which I use for iceray). Additionally, I'd like to rewrite some of the runtime code in Rust and that would not be possible with the C bindings since I would need to work with the *Port classes.

I think your approach might be a bit faster but it was quite easy to create the FFI abstraction. Most of the work on the current bindings was done on the idiomatic interface.

What I can tell from the code snippet is that your bindings are untyped, contrary what I've done so far. I think that it would be valuable to have both.

It would be great to have a look at what you already did and even it we decide to use the C++ API directly, I'm sure there would be some ideas we could borrow.

Is there a chance for you to take part in one of our developer meetups?

[ZhenshengLee]

The rust-binding based on bindgen has been talked about in #879
And @neilisaac you can see this repo of the early work of bindgen generated rust-api https://github.com/ZhenshengLee/iceoryx-rust

Thanks.