6.0.0

[jamescourtney]

Version 6 is a major release for FlatSharp. The major themes of this release are memory efficiency, compatibility, and consolidation. All packages are published on nuget.org.

Memory Efficiency

Thanks to the feedback from folks like @Astn, @TYoungSL, @cristi16, and @tdmowrer, FlatSharp 5.7.0 introduced proper value-type structs. But these were limited and didn't support scenarios like write through due to architectural limitations in FlatSharp. Version 6 addresses these limits and now allows write through on value-type structs!

struct MutableInt (fs_valueStruct) { Value : int; }

table Table (fs_serializer:"Lazy")
{
       IntVector : [ MutableInt ] (fs_writeThrough);
       Int : MutableInt (fs_writeThrough, required);
}

Table t = Table.Serializer.Parse(data);
t.Int = new MutableInt { Value = 3 }; // saves 3 to the underlying buffer!
t.IntVector[3] = new MutableInt { Value = 10; } // overwrites index 3 of the vector with the new value.

Write Through for value-type structs was the last real functionality delta between reference and value structs. Reference structs remain the default for compatibility reasons.

FlatSharp 6 also includes some other memory efficiency goodies:

• Unions are now value types instead of classes, all implementing IFlatBufferUnion<T1, T2, ..., TN>
• ArrayInputBuffer, MemoryInputBuffer, etc are now structs as well. No more extra allocations.
• FlatBufferSerializer exposes a couple of new generic overloads that allow you to avoid boxing your IInputBuffer instance.

With the changes for Value-type structs, input buffers, and unions, it's possible to use FlatSharp without allocating (almost) any GC memory.

Compatibility

FlatSharp version 1.1.0 (!) added the FlatSharp compiler. It evolved organically in the interim time, until it reached the limits of its maintainability. Adding value structs was a particularly challenging feature because of the limits of the compiler package.

Additionally, there were several bugs with the FlatSharp compiler:

• Different namespace resolution rules than flatc.
• At one point, had an off-by-one bug in enum auto-numbering

Essentially -- it was difficult to maintain and only offered a close approximation of the official compiler, which sometimes led to different results.

FlatSharp 6.0.0 drops the home grown compiler and leverages flatc to do the first pass of compilation, which involves interpreting the grammar of FBS files and generating a graph of relationships. The FlatSharp compiler now takes that output and generates the normal FlatSharp code. The FlatSharp compiler package now includes flatc binaries for Windows, Linux, and MacOS. However -- the switch here means that you should carefully validate your generated files, as flatc might have a different opinion about your FBS files than the old FlatSharp compiler did. Additionally, flatc has stricter validation rules for FBS files than the old FlatSharp compiler did, so you may get a few expected errors. Here are some common cases:

• Attribute not declared. flatc expects attributes to be declared like so: attribute "fs_writeThrough"; The top of the file works fine.
• Attribute values must be quoted. some Table (fs_serializer:Lazy) { .. } will no longer work. You need to have quotes around the Lazy.
• Type not found. This generally happens for structs, which need to be defined in reverse order. So if A contains B, B must come before A in the FBS file. Think C code without forward declarations.

If you run into problems, please raise an issue.

Consolidation

FlatSharp 6 leverages some of these architectural changes to make things easier. Previous versions of FlatSharp supported Shared Strings, but did so with a SharedString class. This limitation is the same that blocked value type write through -- FlatSharp expected a single way to read or write a given Type.

FlatSharp 6 removes the SharedString class altogether, but doesn't drop support for shared strings! The generated code is now smart enough to maintain and track context for table fields.

Another piece of consolidation is collapsing PropertyCache, VectorCache, and VectorCacheMutable into a single new deserialization mode: Progressive. Progressive mode offers the invariant that each element of the flatbuffer is read once and then cached. Progressive is very cool because it generally offers the best of both Lazy and Greedy modes, while not preallocating anything. PropertyCache, VectorCache, and VectorCacheMutable are no longer supported. Full documentation can be found in the wiki.

For a quick preview of Progressive, here's a benchmark that shows the different deserialization modes reading a 1000 item value-struct vector, both fully and sparsely with 1 and 5 traversals. While Progressive doesn't win every benchmark, it scores a first place and a bunch of pretty-close second places, which makes it an ideal choice when you aren't sure what the access patterns on a deserialized buffer will be.

Traversal	Option	Traversal Count	Mean	Gen 0	Gen 1	Allocated
Full	Lazy	1	8,863.1 ns	-	-	96 B
Full	Progressive	1	8,073.5 ns	0.7935	0.0305	13,480 B
Full	Greedy	1	7,698.9 ns	0.7172	0.0153	12,160 B
Sparse	Lazy	1	926.1 ns	0.0057	-	96 B
Sparse	Progressive	1	1,062.7 ns	0.1221	-	2,056 B
Sparse	Greedy	1	5,821.3 ns	0.7248	0.0229	12,160 B
Full	Lazy	5	44,034.1 ns	-	-	96 B
Full	Progressive	5	20,029.3 ns	0.7935	0.0305	13,480 B
Full	Greedy	5	15,958.8 ns	0.7019	-	12,160 B
Sparse	Lazy	5	4,467.0 ns	-	-	96 B
Sparse	Progressive	5	2,326.5 ns	0.1221	-	2,056 B
Sparse	Greedy	5	6,698.4 ns	0.7248	0.0229	12,160 B

Odds and Ends

Finally -- FlatSharp 6 is about 10% faster than 5.7.1 for deserialization operations using regular managed arrays. Serialization performance is unchanged from 5.7.1.

You can find the full list of changes in #216, which is rather long, but is the authoritative source on what the breaking changes are. The samples and wiki have been updated to reflect the changes in version 6.

Finally, thanks for using FlatSharp. It's really cool to see people using the project and gaining some benefit from it. If you're using it successfully, it would be great to hear about it!

---

This discussion was created from the release 6.0.0.

[Astn]

Congratulations, great work, great library man!