FlatSharp changelog

Changelog History

• v4.1.0 Changes

  October 17, 2020

  🔖 Version 4.1.0 is a minor release and builds on the performance improvements in 4.0.0.

  🔧 The main improvement in version 4.1.0 is support for new configurations for properties:

  • 👍 Non-virtual properties now supported (setters are required). Non-Virtual properties are always deserialized greedily.

  • 👍 Protected and Protected Internal setters now supported

    [FlatBufferTable]public class MyTable{ [FlatBufferItem(0)] public virtual int VirtualInt { get; protected set; } [FlatBufferItem(1)] public string NonVirtualString { get; protected internal set; } [FlatBufferItem(2)] public virtual int ReadOnlyInt { get; } }

  👍 FBS files also support these:

  table MyTable // nonVirtual is supported at the table level to set a default for all properties.
  {
     VirtualInt:int (setter:"protected");
     NonVirtualString:string (setter:"protectedinternal", nonVirtual);
     ReadOnlyVirtualInt:int (setter:"none");
  }
  

  ➕ Additionally, the FlatSharp compiler now supports the ObsoleteDefaultConstructor attribute on tables and structs to apply a [Obsolete] attribute to the generated default constructor. This can help create immutable objects.

• v4.0.0 Changes

  October 07, 2020

  🔖 Version 4 is a significant milestone for FlatSharp, and represents the culmination of a lot of work. Hope you enjoy it, to the extent that it's possible to enjoy a serialization library!

  What's new?

  Glad you asked!

  • 👌 Support for optional/nullable scalars (tables only) (google/flatbuffers#6014)
  • 👌 Support for "indexed vectors", which are Vectors that look and act like Dictionaries. Under the hood, these are sorted vectors that expose a simpler programming model, so it's no longer necessary to worry about whether a vector is sorted or not. Check out the indexed vectors sample!
  • 👍 Shared strings are now supported in sorted vectors
  • 🆕 New method of publishing benchmark data, benchmarks extended to include .NET 5.0

  Internal stuff

  🐎 Lots of work went into optimizing how the CLR JIT treats FlatSharp's code. Performance is increased anywhere from 10 - 30% relative to version 3.3.1.

  • Much of this improvement was changes to allow the JIT to elide virtual function calls when invoking methods on SpanReader and InputBuffer. More background is available here: dotnet/runtime#32815

  - Other changes involved removing some unnecessary branches and function calls on hot paths

  🔌 FlatSharp's backend was completely rewritten to be more modular, so that future types can be supported more easily. It is now possible (though not advised) to write your own plugins. This amounted to a rewrite of a large part of the code.

  💥 Breaking Changes

  FlatSharp adheres to semantic versioning, and there are breaking public API changes in version 4:

  • SpanWriter has been changed from a class to a struct. It is no longer inheritable. A new ISpanWriter interface has been introduced should you wish to provide your own.
  • UnsafeSpanWriter remains a class, but is sealed.
  • 🚚 The base class InputBuffer has been removed. It has been replaced with IInputBuffer
    • ArrayInputBuffer, MemoryInputBuffer, ReadOnlyMemoryInputBuffer, and the unsafe variants remain the same.
  • 👌 Support for memory vectors has been dropped for all types but byte. This was to address a design oversight where precompiled serializers would produce incorrect results when running on big-endian platforms.
    • Memory<byte> and ReadOnlyMemory<byte> remain supported.

• v3.3.0 Changes

  August 20, 2020

  🔖 Version 3.3.0 of FlatSharp introduces a new feature: String Deduplication, also called Shared Strings. This feature (off by default), enables FlatSharp to only write one instance of a string that occurs many times within your buffer. For buffers with many repeated strings, this can save quite a bit of space in your serialized buffers. Usually, it will slow down serialization and parsing slightly, which is why it's left off by default. For more information, please take a look at the shared strings sample!

  🏗 The FlatSharp compiler has been enhanced to be more friendly, courtesy of @eltone. .fbs.cs files have been moved to the obj directory where they belong, so they won't clutter your solutions any longer. Furthermore, some Unix build issues have been resolved (#54), a first-build bug has been addressed (#45, #55), and gRPC hosting has been extended to support ASP.NET core (#53). Thanks, Anthony!

• v3.2.0 Changes

  July 31, 2020

  🚀 It's been awhile, but FlatSharp has a new release out with support for better unions when using FBS files. So what's new?

  🚀 Let's talk about the problem with unions in prior releases using this FBS schema as our guide:

  table Dog { ... }
  table Cat { ... }
  table Fish { ... }
  
  union FavoritePet { Dog, Cat, Fish }
  
  table Person { FavoritePet:FavoritePet; }
  

  You'd get some code that looked like this:

  [FlatBufferTable]public class Person : object{ [FlatBufferItem(0)] public virtual FlatBufferUnion\<Dog, Cat, Fish\> FavoritePet { get; set; } }
  

  In short, you declared a FlatBufferUnion{T} instance and used the generic parameters of that type to call out the members of the union. When interacting with it, code often looked like this:

  Person p = (...)Dog dog = p.FavoritePet.Item1; // Unintuitive.switch (p.FavoritePet.Discriminator) { case 1: // What does 1 mean?Console.WriteLine("dog"); break; case 2: // catConsole.WriteLine("cat"); break; case 3: default: Console.WriteLine("fish"); break; }
  

  However, simply using a generic type supplied by FlatSharp wasn't very useful because it made the code harder to read. Item1 is just not a good description. The other big problem is a union that has many members. Imagine trying to plumb FlatBufferUnion<T1,...,T10> through your code.

  In version 3.2.0, FlatSharp will generate custom union classes for you when using FBS schemas. In this example, you'd get a FavoritePet class that looks like this:

  public class FavoritePet : FlatBufferUnion\<Dog, Cat, Fish\> { public enum ItemKind : byte { Dog = 1, Cat = 2, Fish = 3, } public ItemKind Kind { get; } public Dog Dog { get; } public Cat Cat { get; } public Fish Fish { get; } }
  

  🏗 This should greatly increase the usability of unions. The final change is a set of methods that have been added to all Union types called Switch. The methods are semantically the same as a switch statement, but with compiler support so you'll get build breaks when a new item is added to the union. This is handy because it ensures that you explicitly address all cases in your code where the new union member could occur. Catching errors at build time is better than runtime!

  FavoritePet pet = person.Pet;string petSays = pet.Switch( caseDefault: () =\> "??", caseDog: () =\> "Woof", caseCat: () =\> "Meow", caseFish: () =\> "gurgle gurgle");
  

• v3.0.0 Changes

  March 30, 2020

  💥 3.0 is a major release of FlatSharp, with new features and bug fixes. Please read the full notes below before upgrading, as there is a breaking change around enums declared in FBS files.

  Compiler Improvements

  • FlatSharp generates copy constructors for you
  • Increased compatibility with the flatc compiler from Google:
    • Support includes
    • Support quoted metadata
    • Fix a bug around the default numbering for enums (read the breaking change below)

  ⚙ Runtime Improvements

  • Usability improvements with some new extension methods on ISerializer<T> for serializing and deserializing.
  • 👌 Support for parsing using ReadOnlyMemory<byte>
  • 👌 Support for Sorted Vectors
  • 🐎 Some scenarios will see a ~10% performance uplift (see the benchmarks folder)

  💥 Breaking Changes

  🚀 This release of FlatSharp fixes a bug related to enum numbering. Enums declared in FBS files in FlatSharp 2.X started their numbering at 1 if left unspecified:

  enum MyEnum : ubyte {
     First, Second, Third
  }
  

  Translated to

  public enum MyEnum : byte { First = 1, Second = 2, Third = 3, }
  

  This was a bug reported by @thomas-t1 in #30. The correct numbering starts at 0. In version 3.X, FlatSharp will generate this code instead:

  public enum MyEnum : byte { First = 0, Second = 1, Third = 2}
  

  ⬆️ This is a problem for any upgrades. If you have been using FlatSharp with FBS files to generate enums, please ensure that you have explicitly set the first member to 1 like so:

  enum MyEnum : ubyte {
     First = 1, Second, Third
  }
  

  This will allow you to preserve the old numbering.

• v2.1.0 Changes

  February 09, 2020

  👍 FlatSharp compiler now supports GRPC definitions in FBS files!

• v2.0.0 Changes

  February 02, 2020

  • 🐎 Performance improvements for Greedy deserialization
  • 💥 Breaking changes on the FlatBufferSerializerFlags enum. It is no longer a flags enum, and has been renamed to FlatBufferDeserializationOption

  Mapping of new value to old value:

  OldValue -> NewValue
  Lazy -> PropertyCache
  CacheListVectorData -> VectorCache
  CacheListVectorData | GenerateMutableObjects -> VectorCacheMutable
  GenerateMutableObjects -> VectorCacheMutable
  GreedyDeserialize -> Greedy
  GreedyDeserialize | Mutable -> GreedyMutable (used by FlatBufferSerializer.Default)
  

  • A new deserialization mode has been added: FlatBufferDeserializationOption.Lazy. In Lazy mode, FlatSharp will always read from the underlying buffer, and nothing is cached.
  • 🏗 Build time generated serializers now include checked in all methods.

• v1.2.0 Changes

  January 30, 2020

  • 🏗 Build time serializer generation! FlatSharp can now be used exclusively at build-time with the FlatSharp.Compiler and FlatSharp.Runtime packages. This removes the dependency on the Roslyn compiler at runtime.
  • 🛠 NullReferenceExceptions with nested structs fixed.
  • FBS files generated formatted C# code.
  • 🐎 Performance optimizations with the CacheListVectorData option.

• v1.1.0 Changes

  January 26, 2020

  • 👌 Support for enums (with the FlatBufferEnum attribute)
  • 🆕 New nuget for compiling FBS schemas into FlatSharp C#.

• v1.0 Changes

  April 16, 2019

  🎉 Initial release of FlatSharp. There are no known issues at the moment with the current code. FlatSharp is schema complete with the exception of Vectors of Unions and built-in enum support.