Merge pull request MessagePack-CSharp#1090 from pCYSl5EDgo/ExperimentalPackageDocumentation

Add descriptions about MessagePack.Experimental.

Author: AArnott

README.md

@@ -44,6 +44,7 @@ MessagePack has a compact binary size and a full set of general purpose expressi
     - [Be careful when copying buffers](#be-careful-when-copying-buffers)
     - [Choosing compression](#choosing-compression)
 - [Extensions](#extensions)
+- [Experimental Features](#experimental-features)
 - [High-Level API (`MessagePackSerializer`)](#high-level-api-messagepackserializer)
     - [Multiple MessagePack structures on a single `Stream`](#multiple-messagepack-structures-on-a-single-stream)
 - [Low-Level API (`IMessagePackFormatter<T>`)](#low-level-api-imessagepackformattert)
@@ -983,6 +984,16 @@ You can make your own extension serializers or integrate with frameworks. Let's
 * [WebApiContrib.Core.Formatter.MessagePack](https://github.com/WebApiContrib/WebAPIContrib.Core#formatters) - supports ASP.NET Core MVC ([details in blog post](https://www.strathweb.com/2017/06/using-messagepack-with-asp-net-core-mvc/))
 * [MessagePack.MediaTypeFormatter](https://github.com/sketch7/MessagePack.MediaTypeFormatter) - MessagePack MediaTypeFormatter
 
+## Experimental Features
+
+MessagePack for C# has experimental features which provides you with very performant formatters. There is an official package.
+
+```ps1
+Install-Package MessagePack.Experimental
+```
+
+For detailed information, see: [Experimental.md](src/MessagePack.Experimental/Experimental.md)
+
 # API
 
 ## High-Level API (`MessagePackSerializer`)

src/MessagePack.Experimental/Experimental.md

@@ -0,0 +1,11 @@
+# MessagePack.Experimental
+
+This C# project is the experimental project for the features which are very complex, unstable or unsafe.
+
+- [HardwareIntrinsics](HardwareIntrinsics/HardwareIntrinsics.md)
+- [UnsafeUnmanagedStructFormatter](UnsafeUnmanagedStructFormatter/UnsafeUnmanagedStructFormatter.md)
+
+**Caution!**
+
+`MessagePack.Experimental` only targets `.NET Core 3.1` and above.
+You can not use this in Unity and .NET Framework.

src/MessagePack.Experimental/HardwareIntrinsics/HardwareIntrinsics.md

@@ -0,0 +1,24 @@
+# Abstract
+
+`Hardware Intrinsics` is a feature in order to utilize maximum power of the cpu.
+You can serialize/deserialize primitive type array much faster than current implementation!
+
+Supported types
+
+- `sbyte[]`
+- `short[]`
+- `int[]`
+- `bool[]`
+- `float[]`
+- `double[]`
+
+# Usage
+
+```csharp
+var resolver = MessagePack.Resolvers.CompositeResolver.Create(new[] { PrimitiveArrayResolver.Instance, MessagePack.Resolvers.StandardResolver.Instance });
+```
+
+# When will this feature become official?
+
+- The MessagePack-CSharp's lowest target framework is greater or equals to `.NET Core 3.1`.
+- The current very complex and hard to understand implementation is rewritten.

src/MessagePack.Experimental/UnsafeUnmanagedStructFormatter/UnsafeUnmanagedStructFormatter.md

@@ -0,0 +1,29 @@
+# Abstract
+
+`UnsafeUnmanagedStructFormatter`s (de)serialize the blittable value(s) directly.
+They are very performant but unstable against the endian.
+
+You should be careful not to share the encoded byte[] among the different endian environments.
+
+Supported types (T where T : unamanaged)
+
+- `T` → `UnsafeUnmanagedStructFormatter<T>`
+- `T[]` → `UnsafeUnmanagedStructArrayFormatter<T>`
+- `Memory<T>` → `UnsafeUnmanagedStructMemoryFormatter<T>`
+- `ReadOnlyMemory<T>` → `UnsafeUnmanagedStructReadOnlyMemoryFormatter<T>`
+- `ReadOnlySequence<T>` → `UnsafeUnmanagedStructReadOnlySequenceFormatter<T>`
+
+# Usage
+
+```csharp
+var resolver = MessagePack.Resolvers.CompositeResolver.Create(
+    new[] { new UnsafeUnmanagedStructFormatter<Matrix4x4>(typeCode: 96) },
+    new[] { MessagePack.Resolvers.StandardResolver.Instance });
+```
+
+The constructor takes 1 sbyte value.
+The sbyte value is the extension type code embedded in serialized byte sequence.
+
+# When will this feature become official?
+
+- Requests are needed.