DOCSP-40227: memory serialization (#588)

* DOCSP-40227: memory serialization

* add note

* MM PR fixes 1

* BD tech review comments 1

(cherry picked from commit 611a739)

Author: rustagir

source/fundamentals/serialization.txt

@@ -140,6 +140,62 @@ Implementing the `IBsonArraySerializer
 interface enables the driver to access serialization information for individual
 items in an array.
 
+.. _csharp-array-serialization:
+
+Improve Array Serialization Performance
+---------------------------------------
+
+You can improve your application's performance by representing
+arrays of primitives as `Memory<T> <https://learn.microsoft.com/en-us/dotnet/api/system.memory-1?view=net-8.0>`__
+and `ReadOnlyMemory<T> <https://learn.microsoft.com/en-us/dotnet/api/system.readonlymemory-1?view=net-8.0>`__
+structs instead of by using types such as standard {+language+} arrays or
+``BsonArray`` objects. The driver implements fast serialization and
+deserialization paths for ``Memory<T>`` and ``ReadOnlyMemory<T>``, which
+enhances speed and reduces memory usage.
+
+.. note::
+
+   Truncation and overflow checks are not supported for ``Memory<T>`` or
+   ``ReadOnlyMemory<T>``, but these checks are implemented for standard
+   arrays.
+
+You can effect these performance improvements by storing the following
+primitive types in ``Memory<T>`` or ``ReadOnlyMemory<T>`` structs:
+
+- ``bool``
+- ``sbyte``
+- ``byte``
+- ``char``
+- ``short``
+- ``ushort``
+- ``int``
+- ``uint``
+- ``long``
+- ``ulong``
+- ``float``
+- ``double``
+- ``decimal``
+
+The following example defines a ``Line`` POCO that contains array fields
+modeled by ``Memory`` and ``ReadOnlyMemory`` structs:
+
+.. literalinclude:: /includes/fundamentals/code-examples/MemorySerialization.cs
+   :start-after: start-line-class
+   :end-before: end-line-class
+   :language: csharp
+   :dedent:
+
+The following document represents how a sample ``Line`` object is
+represented in MongoDB:
+
+.. code-block:: json
+
+   {
+     "_id": ...,
+     "X": [ 1, 2, 3, 4, 5 ],
+     "Y": [ 1, 1.409999966621399, 1.7300000190734863, 2, 2.240000009536743 ]
+   }
+
 Additional Information
 ----------------------
 

source/includes/fundamentals/code-examples/MemorySerialization.cs

@@ -0,0 +1,37 @@
+using MongoDB.Bson;
+using MongoDB.Bson.Serialization.Conventions;
+using MongoDB.Driver;
+
+public class Program
+{
+  public static void Main(string[] args)
+  {
+    // Replace with your connection string
+    const string uri = "<connection string>";
+
+    var mongoClient = new MongoClient(uri);
+    var database = mongoClient.GetDatabase("db");
+    var _collection = database.GetCollection<Line>("lines");
+
+    var line = new Line
+    {
+      X = new Memory<int>(new[] { 1, 2, 3, 4, 5 }),
+      Y = new ReadOnlyMemory<float>(new[] { 1f, 1.41f, 1.73f, 2f, 2.24f })
+    };
+
+    var filter = Builders<Line>.Filter.Empty;
+
+    var result = _collection.Find(filter).FirstOrDefault().ToJson();
+    Console.WriteLine(result);
+  }
+
+}
+
+// start-line-class
+public class Line
+{
+  public ObjectId Id { get; set; }
+  public Memory<int> X { get; set; }
+  public ReadOnlyMemory<float> Y { get; set; }
+}
+// end-line-class

source/whats-new.txt

@@ -296,7 +296,8 @@ The 2.26 driver release includes the following new features:
 - Enabled use of native ``crypto`` in ``libmongocrypt`` bindings.
 
 - Added support for serialization of ``Memory`` and ``ReadOnlyMemory``
-  structs.
+  structs. To learn more about implementing these types, see the
+  :ref:`csharp-array-serialization` section of the Serialization guide.
 
 - Added support for the GCP Identity Provider when using the
   ``MONGODB-OIDC`` authentication mechanism. To learn more, see