7.0.0

[jamescourtney]

Welcome to FlatSharp 7! Version 7 is a major release that includes many under-the-hood improvements such as .NET 7 support, performance improvements for several cases, generated code deduplication, experimental object pools, and some big breaking changes. This is a long list of changes, so buckle up!

Runtime-Only Mode Deprecation

Let's start with the bad news: Reflection-only Runtime mode is not making the jump to FlatSharp 7.

The original version of FlatSharp did not include a compiler or support for FBS files. Instead, it used attribute-based reflection like so many other .NET serializers do with attributes like [FlatBufferTable] which allowed generation of code at runtime. FlatSharp.Compiler was introduced in early 2020, and in version 6 it was ported to use flatc as its parser instead of the custom grammar. Today, there is really no reason to use reflection mode any longer. The FlatSharp compiler is mature and enables all of the same semantics, with a slew of additional benefits over runtime mode:

• Support for AOT / Unity
• Cross-platform compatibility with other FBS compilers such as flatc and flatcc.
• No runtime overhead for code generation
• No package dependencies on Roslyn
• Errors caught at build time rather than runtime
• Custom Union types
• gRPC integration
• Copy/clone constructors
• ...and many others

For these reasons, the trend has been that most new features and development of FlatSharp use the compiler rather than the reflection-only mode. So in version 7, FlatSharp is dropping support for runtime code generation. This is a difficult decision, but one that allows the project to keep moving forward and is broadly aligned to most customer's usage of FlatSharp, along with the bigger trends in .NET, such as AOT and source generators. Going forward, only two packages will see new versions published: FlatSharp.Runtime and FlatSharp.Compiler.

Removing Runtime-only mode removes an entire class of human error from FlatSharp and makes AOT easier to reason about. One immediate benefit of this change is that the FlatSharp.Runtime package now has no internal reflection calls any longer, which makes AOT less error-prone. Unfortunately, it does also remove support for some features such as Type Facades.

Array Vector and fs_nonVirtual Deprecation

In the interest of helping engineers make good decisions about how to use FlatSharp, Array vectors (fs_vector:"Array") and non-virtual properties have been deprecated. These behave very unpredictably with FlatSharp, because...

• They must be accessed greedily, which means they don't perform well at all with Lazy deserialization. Accessing an Array property on a Lazy object simply allocates a new array each time. Not good!
• They cannot satisfy FlatSharp's immutability promises in Lazy, Greedy, and Progressive modes
• They cannot support WriteThrough (fs_writeThrough)
• Virtual methods and interfaces, such as IList<T>, provide much of the performance, with an order of magnitude more flexibility.

When serializing Vectors, FlatSharp does still attempt to devirtualize IList<T> and IReadOnlyList<T> to arrays for the performance boost, but this is more an implementation detail of the handling for IList<T> than it is about continuing to support arrays explicitly.

.NET 7 Support

FlatSharp version 7 supports .NET 7. What a happy coincidence! This is not a major change. However, there are a few things worth calling out.

The first is that IFlatBufferSerializable<T> has a few new members when using .NET 7:

public interface IFlatBufferSerializable<T> where T : class
{
      ISerializer<T> Serializer { get; } // this already existed

#if NET7_0_OR_GREATER
     static abstract ISerializer<T> LazySerializer { get; }
     static abstract ISerializer<T> ProgressiveSerializer { get; }
     static abstract ISerializer<T> GreedySerializer { get; }
     static abstract ISerializer<T> GreedyMutableSerializer { get; }
#endif
}

This allows writing code like this:

public static T Parse<T>(byte[] buffer) where T : class, IFlatBufferSerializable<T>
{
    // All serializer types are available now, as well
    return T.LazySerializer.Parse(buffer);
}

Next, FlatSharp 7 supports required members. That is, when you specify the required FBS attribute, the generated C# also contains that annotation:

table RequiredTable
{
     Numbers : [ int ] (required);
}

Now generates:

public class RequiredTable
{
    public required virtual IList<int> Numbers { get; set; }
}

This is, of course, only available for those of you using .NET 7. If you aren't ready for .NET 7 just yet, then no problem; FlatSharp will continue to generate code that works with .NET 6, .NET Standard 2.0, and .NET Standard 2.1, though you may see #if NET7_0_OR_GREATER peppered throughout your generated code now!

Finally, FlatSharp 7 fully supports .NET 7 AOT. Effort has been made to remove the last vestiges of reflection from the FlatSharp.Runtime package.

Code Deduplication

Previous versions of FlatSharp generated separate code for each root type. That is, imagine this schema:

// A big table
table Common
{
    A : string;
    B : string;
    ...
    Z : string;
}

table Outer1 (fs_serializer) { C : Common }
table Outer2 (fs_serializer) { C : Common }

In this case, FlatSharp 6 and below would generate 2 full serializers and parsers for Common, since it is used by both Outer1 and Outer2. This led to cases where commonly-used large tables would have more than one serializer implementation generated. Such code duplication leads to poor cache performance, poor utilization of the branch predictor, and an explosion of code when the type in question is used in multiple places, such as gRPC definitions.

FlatSharp 7 does the expected thing and generates only one serializer/parser for each type. As part of this change, FlatSharp 7 emits all serializer types, which comes with the happy accident of allowing you to specify it at runtime:

ISerializer<T> lazySerializer = Outer1.Serializer.WithSettings(settings => settings.UseLazyDeserialization());

Performance Improvements

FlatSharp 7 improves the performance of IList<T> vectors by enabling devirtualization of internal method calls. Previous versions of FlatSharp defined the base vector along these lines:

public abstract class BaseVector<T> : IList<T>
{
    public T this[int index]
    {
        get => this.ItemAtIndex(index);
    }

    protected abstract T ItemAtIndex(int index);
}

Virtual methods do have a cost, because the assembly must look first to the vtable to then jump to the actual methods. A better way to write the same code is with this technique:

public interface IVectorAccessor<T>
{
    T GetItemAtIndex(int index);
}

public class Vector<T, TVectorAccessor>
    where TVectorAccessor : struct, IVectorAccessor<T>
{
    private readonly TVectorAccessor accessor;
    
    public T this[int index]
    {
        get => this.accessor.ItemAtIndex(index);
    }
}

But wait! Aren't these the same thing? Both are calling a virtual method after all. The trick is subtle, and involves generics and structs. Stephen Cleary writes about it more clearly than I can here.

This technique is not new to FlatSharp. Support for this trick was added in Version 4, and why IInputBuffer implementations have been structs and the entire Parsing stack is templatized. However, the opportunity to do the same for vectors was only recently discovered, and the improvements are impressive. Iterating through a Lazy vector is often 20-50% faster.

Additionally, VTable parsing has been improved by several whole nanoseconds! Joking aside, this is an important thing since every table has a VTable, so this is one of the operations that FlatSharp does at the very core, and the benefit multiplies with the number of tables you read. Only tables with 8 or fewer fields benefit from this optimization. Larger tables fall back to the previous behavior.

Here's a quick teaser of FlatSharp parse/traverse performance of a vector of structs, both reference and value:

Method	Mean	Error	StdDev	P25	P95	Code Size	Gen0	Allocated
Parse_Vector_Of_ReferenceStruct_FlatSharp7	247.95 ns	22.909 ns	8.169 ns	242.53 ns	258.21 ns	291 B	0.0787	1320 B
Parse_Vector_Of_ReferenceStruct_FlatSharp6	324.56 ns	4.396 ns	1.568 ns	323.32 ns	326.39 ns	263 B	0.0787	1320 B
Parse_Vector_Of_ValueStruct_FlatSharp7	93.86 ns	1.254 ns	0.447 ns	93.71 ns	94.29 ns	279 B	0.0072	120 B
Parse_Vector_Of_ValueStruct_FlatSharp6	194.78 ns	8.377 ns	2.987 ns	192.61 ns	197.42 ns	251 B	0.0072	120 B

Object Pooling

Object Pooling is a technique that can be used to reduce allocations by returning them to a pool and re-initializing them later. FlatSharp 7's object pool is experimental. The intent of this release is to get the feature into the wild and how well it works. With Object Pooling enabled, it is possible to use FlatSharp in true zero-allocation mode. The wiki has full details.

Field Name Normalization

In version 6.2.0, FlatSharp introduced an optional switch to normalize snake_case fields into UpperPascalCase. This was off by default in version 6 for compatibility reasons. In FlatSharp 7, field name normalization is on by default. There are three ways to disable this:

Add this to your csproj file:

<PropertyGroup>
  <FlatSharpNameNormalization>false</FlatSharpNameNormalization>
</PropertyGroup>

Annotate your tables and structs with fs_literalName:

table MyTable (fs_literalName)
{
   wont_be_normalized : string;
   wont_be_normalized_either : string;
}

struct MyStruct
{
    will_be_normalized : int;
    wont_be_normalized : int (fs_literalName);
}

Finally, if you use the FlatSharp compiler as a command line tool, you can pass --normalize-field-names false as a command line argument.

Unsafe External Value Structs

FlatSharp 7 adds a new annotation (fs_unsafeExternal) that may be applied to value structs and enums. The annotation indicates to FlatSharp that the type is defined externally to the FBS Schema. Serializers are generated based on the definition, but no type definitions are emitted. This allows doing things like referencing hardware accelerated types such as System.Numerics.Vector3 from a FlatSharp schema:

struct Vec3 (fs_valueStruct, fs_unsafeExternal:"System.Numerics.Vector3")
{
    x : float32;
    y : float32;
    z : float32;
}

table Path { Points : [ Vec3 ]; }

In this example, the Points property in the Path table will be of type IList<System.Numerics.Vector3>. There are a few catches to this that you need to be aware of. The first is that it's not safe. FlatSharp is able to provide exactly two validations:

• The size of the external struct matches the size of the struct defined in the FBS schema. A runtime exception will be thrown if they do not match.
• The machine running the code is a little endian architecture. If using a big endian machine, a runtime exception will be thrown. FlatBuffers is a little-endian format, which means a BE machine wouldn't be able to read the data correctly.

There are many additional things beyond the size of the struct and the endianness of the machine that FlatSharp cannot validate with external structs:

• The alignment of the data
• The validity and layout of the data
• That the definition will work on all machines. Some value structs have different sizes depending on the machine where they run, such as System.Numerics.Vector<byte>. Vector<byte> is 32 bytes when running under JIT on a machine supporting AVX2. In the future it maybe 64 bytes on an AVX512 machine. Or it might be 16 bytes if using .NET 7 AOT compilation.
• That the output will be compatible with the same schema when run with flatc or flatcc.

External structs can be a powerful tool, but they are risky and need thorough testing to ensure correct behavior. If in doubt, it is advisable to simply extend the partial struct declarations and add an implicit conversion operator to the value struct in question.

Unsafe Unions

In other Unsafe news, FlatSharp 7 supports unsafe unions. Unsafe unions are optimizations that apply to unions consisting only of value types. Imagine this FBS schema:

attribute "fs_valueStruct";
attribute "fs_unsafeUnion";

struct FourBytes (fs_valueStruct) { x : int; }
struct EightBytes (fs_valueStruct) { x : long; }
struct SixteenBytes (fs_valueStruct) { x : [ long : 2 ]; }

union MyUnion { FourBytes, EightBytes, SixteenBytes }
union MyUnsafeUnion (fs_unsafeUnion) { FourBytes, EightBytes, SixteenBytes }

Previous versions of FlatSharp would box those value types into an object inside the union:

public struct MyUnion
{
     // structs get boxed in here too.
     private readonly object value;
}

Unsafe unions store their data as a fixed array corresponding to the size of the largest element:

public unsafe struct MyUnsafeUnion : IFlatBufferUnion<EightByteStruct, TenByteStruct, SixteenByteStruct>
{
     // 16 corresponds to the size of the biggest struct in the union.
     private fixed byte[16] value;
}

This allows MyUnsafeUnion to carry all of the values for all of the value types in a single fixed element, without the need for boxing or allocations! There are a couple of caveats to this feature:

• fs_unsafeUnion will raise an error if there are any reference types in the union. Experimentally, performance degrades significantly when a union carries a mix of object and fixed byte[] elements.
• Unsafe unions are compatible with fs_unsafeExternal value structs.
• FlatSharp will check the size of your structs at runtime to ensure they are the same as what the FlatSharp compiler thought they were. Like fs_unsafeExternal value structs, you can get runtime exceptions.
• This requires compiling with <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
• As with all unsafe features, FlatSharp tries to do the right thing, but it's a use-at-your-own risk feature, and you ultimately own testing and validation.

Unsafe unions offer reduced allocations and increased performance when traversing a vector:

Method	Mean	Error	StdDev	P25	P95	Code Size	Gen0	Allocated
ParseAndTraverse_SafeUnionVector	511.10 ns	16.573 ns	5.910 ns	506.62 ns	519.09 ns	1,370 B	0.0544	912 B
ParseAndTraverse_UnsafeUnionVector	396.93 ns	12.903 ns	3.351 ns	394.61 ns	401.33 ns	1,339 B	0.0076	128 B

Breaking Changes

Even though FlatSharp 7 is a major release, there are not a ton of breaking changes if you are using the FlatSharp.Compiler package, so upgrading should be straightforward.

FlatSharp Package (Runtime Mode)

• This package has been deprecated and will not be updated to version 7. If you need help upgrading, please raise an issue in this repository.

FlatSharp.Runtime Package

• IInputBuffer2 has been deleted and merged into IInputBuffer. Assorted changes have been made to IInputBuffer.
• The 4 Switch methods on Unions have been deleted. Please use the new Accept/Visitor pattern instead.
• ISerializer<T>.WithSettings now accepts a delegate instead of a settings object. This change is largely semantic but allows easier usage.
• ISerializer<T> properties CSharp, Assembly, and AssemblyBytes have been removed.
• ISerializer<T>.Parse now accepts an optional DeserializationMode argument.

FlatSharp.Compiler Package

• Array vectors are now deprecated. The only valid types of vectors are: IList, IReadOnlyList, IIndexedVector, Memory, and ReadOnlyMemory.
• The fs_nonVirtual attribute no longer has any meaning. All properties are virtual now.
• Vectors of ubyte now default to using Memory instead of IList if no type is specified.
• Field name normalization is now on by default instead of off by default as discussed above.
• The compiler now requires .NET 6 or later to be installed on the build machine. The generated code remains compatible with all supported runtimes.
• The compiler now expects to receive all .FBS files for a single project in one invocation. The --input parameter now accepts a semicolon-delimited list of files: dotnet FlatSharp.Compiler.dll --input "file1.fbs;file2.fbs;file3.fbs" --output .
• Since the compiler expects to receive all files in one invocation, it now writes generated code to FlatSharp.generated.cs instead of SchemaName.fbs.generated.cs. Note: You may experience build errors after upgrading due to type conflicts. Be sure and clean your obj folder of generated files first.

New Contributors

• @joncham made their first contribution in Add fs_preserveFieldCasing attribute #306

Full Changelog: 6.3.3...7.0.0

---

This discussion was created from the release 7.0.0.