Crate flatbuffers_owned

This small Rust crate provides a wrapper struct for generated Rust FlatBuffers that allows them to be used as owned types.
A owned FlatBuffer does not reference its source data and can therefore be easily moved into another thread.

Quickstart

Use the flatbuffers_owned! convenience macro on your FlatBuffers to implement the required trait and introduce a type alias for each owned FlatBuffer.

Generate the OwnedMessage type alias for the Message FlatBuffer:

flatbuffers_owned!(Message);

Receive a byte slice, create a boxed slice, and initialize the owned flatbuffer:

let message_bytes: &[u8] = receive_message_bytes();
let message_bytes: Box<[u8]> = Box::from(message_bytes);

let owned_message = OwnedMessage::new(message_bytes).unwrap();

Access the actual FlatBuffer:

let message: Message = owned_message.as_actual();

assert_eq!(message.get_text().unwrap(), "Hello, world!");

Error-Handling

The new() constructor always verifies the raw FlatBuffer bytes using the FlatBuffer’s built-in run_verifier() method.
Since there can always be a faulty byte-slice passed, you need to check the returned Result of the constructor:

for id in message_ids {
    let message_bytes = Box::from(receive_message_bytes());

    let owned_message = OwnedMessage::new(message_bytes);

    match owned_message {
        Ok(message) => {
            // ... process message
        },
        Err(e) => {
            println!("Failed to parse Message: {}", e);
            // ... handling logic
        },
    }
}

Approach

The wrapper struct

The wrapper struct is a newtype for a Box<u8> that accepts a FlatBuffer as the generic type.
With the flatbuffers_owned! convenience macro we get a type alias that just masks this wrapper struct.

pub type OwnedMessage = OwnedFlatBuffer<Message<'static>>;

So instead of OwnedMessage, we can just as well use OwnedFlatBuffer<Message<'static>>.

let owned_message = OwnedFlatBuffer::<Message<'static>>::new(message_bytes).unwrap();

As you may have noticed, the 'static lifetime is then always present when working with the OwnedFlatBuffer.
However, this can be misleading, because the OwnedFlatBuffer does not actually reference anything in the 'static lifetime.
The lifetime is only required by the FlatBuffer struct.
So to make the code more readable, we have the type alias.

Deref to &u8

The OwnedFlatBuffer struct de-references itself to its underlying bytes slice.
A Deref to the actual FlatBuffer struct is sadly not possible, since the associated type of the Deref trait can not carry a lifetime.

Open to Feedback

If you have any ideas for improvements or would like to contribute to this project, please feel free to open an issue or pull request on GitHub.
I will also be happy for any general tips or suggestions given that this is my first (published) library ever. :)

Macros

• flatbuffers_owned
  This macro implements the RelaxedFollow trait for your FlatBuffer and creates a type alias for the corresponding OwnedFlatBuffer type. This is the go-to macro for creating an owned FlatBuffer type.

Structs

• OwnedFlatBuffer
  This is the FlatBuffer wrapper struct. It is a newtype for a Box<u8> that accepts a FlatBuffer as the generic type. The lifetime parameter of the FlatBuffer type is nowhere used and can be safely set to 'static.

Traits

• OwnedFlatBufferTrait
  The trait for owned FlatBuffers.
• RelaxedFollow
  This trait allows a .follow() method that returns a FlatBuffer with the lifetime of the provided byte slice.