Crate flatbuffers_owned

A Rust crate that enables a more flexible usage of FlatBuffers.

Using the flatbuffers_owned! macro, you can generate wrapper structs for your flatc generated Rust FlatBuffers.
The generated wrapper structs utilize more flexible lifetimes to access the actual underlying FlatBuffer structure.
As the lifetimes are more relaxed, the raw FlatBuffer bytes can be owned and moved along, or be referenced with any lifetime available.

Usage

Add this to your Cargo.toml:

[dependencies]
flatbuffers-owned = "0.2"

Quickstart

Use the flatbuffers_owned! macro on your FlatBuffers to generate the wrapper structs.

This generates a RelaxedMessage wrapper-struct and a OwnedMessage type alias for the Message FlatBuffer:

use flatbuffers_owned::*;

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 Relaxed{FLATBUFFER_NAME} wrapper struct is a Newtype which can wrap any struct that can convert to a byte slice reference. (where TBuffer: AsRef<[u8]>)
This struct can be used with buffers that fully own its memory, or only hold a shared-reference.

The Owned{FLATBUFFER_NAME} type alias generated along the wrapper struct just predefines the TBuffer generic.
For our Message example FlatBuffer, the generated type alias code would be the following:

pub type OwnedMessage = RelaxedMessage<Box<[u8]>>;

Deref to &u8

The RelaxedFlatBufferTrait enforces a de-reference to the underlying u8 byte slice.
A de-reference 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.

I will also be happy for any general tips or suggestions given that this is my first (published) library ever. :)

Macros

• flatbuffers_owned
  Use this macro on your FlatBuffers to generate the required code to start using this crate.

Traits

• RelaxedFlatBufferTrait
  This trait serves as the foundation for this crate.
  It allows access to the underlying FlatBuffer using the as_actual() method.
  The lifetimes used here are more relaxed than those in the flatc generated code.
  For example, it could be implemented for a fully owned Box<\[u8\]> new-type or even a reference to memory that has been temporarily pinned following a DB query.
• RelaxedFollowTrait
  This trait allows a .follow() method that returns a FlatBuffer with the lifetime of the provided byte slice.