Migrant - 快速和灵活的序列化框架（migrant immigrant emigrant区别）

Migrant - 快速和灵活的序列化框架（migrant immigrant emigrant区别）

Migrant 0.14

This is the Migrant project by Antmicro, a fast and flexible serialization framework usable for undecorated classes, written in C#.

Table of Contents

IntroductionDirectory organizationUsageFeaturesDownloadCompilationMore informationLicenceAuthors

Introduction

Migrant is a serialization framework for .NET and Mono projects. Its aim is to provide an easy way to serialize complex graphs of objects, with minimal programming effort.

Directory organization

There are three main directories:

Migrant - contains the source code of the library;Tests - contains unit tests (we're using NUnit);PerformanceTester - contains performance assessment project;

There are two solution files - Migrant.sln, the core library, and MigrantWithTests.sln, combining both tests project and Migrant library.

Usage

Here we present some simple use cases of Migrant. They are written in pseudo-C#, but can be easily translated to other CLI languages.

Simple serialization

var stream = new MyCustomStream();var myComplexObject = new MyComplexType(complexParameters);var serializer = new Serializer();serializer.Serialize(myComplexObject, stream);stream.Rewind();var myDeserializedObject = serializer.Deserialize(stream);

Open stream serialization

Normally each serialization data contains everything necessary for serialization like type descriptions. Those data, however, consume space and sometimes one would like to do consecutive serializations where each next one would reuse context just as if they happen as one. In other words, serializing one object and then another would be like serializing tuple of them. This also means that if there is a reference to an old object, it will be used instead of a new object serialized second time. Given open stream serialization session is tied to the stream. API is simple:

var serializer = new Serializer();using(var osSerializer = serializer.ObtainOpenStreamSerializer(stream)){ osSerializer.Serialize(firstObject); osSerializer.Serialize(secondObject);}

Here's deserialization:

var serializer = new Serializer();using(var osSerializer = serializer.ObtainOpenStreamDeserializer(stream)){ var firstObject = osSerializer.Deserialize(); var secondObject = osSerializer.Deserialize();}

But what if you'd like to deserialize all object of a given type until the end of stream is reached? Here's the solution:

osDeserializer.DeserializeMany()

which returns lazy IEnumerable.

As default, all writes to the stream are buffered, i.e. one can be only sure that they are in the stream after calling Dispose() on open stream (de)serializer. This is, however, not useful when underlying stream is buffered independently or it is a network stream attached to a socket. In such cases one can disable buffering in Settings. Note that buffering also disables padding which is normally used to allow speculative reads. Therefore data written with buffered and unbuffered mode are not compatible.

Reference preservation

Let's assume you do open stream serialization. In first session, some object, let's name it A, is serialized. In the second session, among others, A is serialized again - the same exact instance. What should happen? We prefer when reference is preserved, so that when A is serialized in second session, actually only its id goes to the second session - pointing to the object from the first session. However, to provide such feature we have to keep reference to A between sessions - to check whether it is the same instance as previously serialized. This means that until open stream serializer is disposed, a reference to A is held, hence it won't be collected by GC. To prevent this unpleasant situation we could use weak references. Unfortunately, as it turned out, with frequent serialization of small objects this can completely kill Migrant's performance - which is a core value in our library. So, to sum it up we offer user to choose from three mentioned options with the help of Settings class. The possible values of an enum ReferencePreservation are:

DoNotPreserve - each session is treated as separate serialization considering references;Preserve - object identity is preserved but they are strongly referenced between sessions;UseWeakReference - best of both worlds conceptually, but can completely kill your performance.

Choose wisely.

Deep clone

var myComplexObject = new MyComplexType(complexParameters);var myObjectCopy = Serializer.DeepCopy(myComplexObject);

Simple types to bytes

var myLongArray = new long[] { 1, 2, ... };var myOtherArray = new long[myLongArray.Length];var stream = new MyCustomStream();using(var writer = new PrimitiveWriter(stream)){ foreach(var element in myLongArray) { writer.Write(element); }}stream.Rewind();using(var reader = new PrimitiveReader(stream)){ for(var i=0; i

Surrogates

var serializer = new Serializer();var someObject = new SomeObject();serializer.ForObject().SetSurrogate(x => new AnotherObject());serializer.Serialize(someObject, stream);stream.Rewind();var anObject = serializer.Deserialize