Home

FlatBuffers.jl Documentation

Overview

FlatBuffers.jl provides native Julia support for reading and writing binary structures following the google flatbuffer schema (see here for a more in-depth review of the binary format).

The typical language support for flatbuffers involves utilizing the flatc compiler to translate a flatbuffer schema file (.fbs) into a langugage-specific set of types/classes and methods. See here for the official guide on writing schemas.

This Julia package provides the serialization primitives used by code that has been generated by flatc. Since it was originally built without flatc support, it can also be used as a minimal set of macros to provide flatbuffer-compatible serialization of existing Julia types. This has led to the Julia code generated by flatc appearing somewhat more readable than for other languages.

For example, for this schema:

namespace example;

table SimpleType {
  x: int = 1;
}

root_type SimpleType;

the code generated by flatc looks like this:

module Example

using FlatBuffers
@with_kw mutable struct SimpleType
    x::Int32 = 1
end

# ... other generated stuff
end

If you don't want to write a schema, you can pepper your existing Julia types with these macros and then call the functions below to produce flatbuffer-compatible binaries.

Usage

FlatBuffers provides the following functions for reading and writing flatbuffers:

FlatBuffers.serialize(stream::IO, value::T) 
FlatBuffers.deserialize(stream::IO, ::Type{T})

These methods are not exported to avoid naming clashes with the Serialization module. For convenience, there are also two additional constructors defined for each generated type:

Here is an example showing how to use them to serialize the example type above.

import FlatBuffers, Example

# create an instance of our type
val = Example.SimpleType(2)

# serialize it to example.bin
open("example.bin", "w") do f FlatBuffers.serialize(f, val) end

# read the value back again from file
val2 = open("example.bin", "r") do f Example.SimpleType(f) end

In addition, this package provides the following types and methods, which are useful when inspecting and constructing flatbuffers:

Methods for Generated Types

For a generated type T, in addition to the constructors mentioned above:

Circular References

It's a bit unfortunate that the flatbuffers example uses mutually referential types, something which Julia doesn't have support for yet. However, there is a workaround - by modifying the code generated by flatc slightly to add a type parameter, we can refer to a type that hasn't yet been defined.

FlatBuffers.@with_kw mutable struct Monster{T}
    # ...
    test::T = nothing
    # ...
end

In general though, try to avoid schemas which introduce these kinds of circular references. For the full Monster example see the test suite here.

Internal Utilities

These functions are used by the code generated by flatc. Documentation is also included for many internal methods and may be queried using ? at the REPL.