Microsoft.IO.RecyclableMemoryStream

Microsoft.IO.RecyclableMemoryStream is a high-performance replacement for System.IO.MemoryStream. It is designed to improve application performance and reduce Garbage Collection (GC) overhead by pooling underlying buffers instead of pooling the stream objects themselves.

Key Benefits:

• Reduces LOH Allocations: Uses pooled buffers to avoid Large Object Heap fragmentation.
• Lower GC Pressure: Reduces Gen 2 collections and GC pause times.
• Memory Safety: Includes bounded pool sizes to prevent memory leaks and fragmentation.
• High Performance: Supports modern memory types like Span<byte>, ReadOnlySpan<byte>, ReadOnlySequence<byte>, and Memory<byte>.
• Observability: Provides metrics, logging, and debug features like call stack recording for leaked streams.

The Microsoft.IO namespace provides two primary classes for managing memory streams efficiently while reducing pressure on the Garbage Collector (GC):

• RecyclableMemoryStream: A MemoryStream implementation designed to handle potentially large buffers by using pooled memory.
• RecyclableMemoryStreamManager: The central manager responsible for maintaining and managing pools of RecyclableMemoryStream objects.

The Options class allows you to customize the behavior of a RecyclableMemoryStreamManager. You can use the default constructors to create an Options object with standard settings or use the parameterized constructor to specify common options immediately.

Common configuration areas include:

• Pooling limits: Controlling MaximumBufferSize, MaximumSmallPoolFreeBytes, and MaximumLargePoolFreeBytes to manage how much memory is kept in pools.
• Buffer sizing: Adjusting BlockSize and LargeBufferMultiple to define how memory blocks are allocated.
• Safety and Debugging: Using GenerateCallStacks for debugging (not for production) or ThrowExceptionOnToArray to prevent expensive ToArray() calls.

When configuring the RecyclableMemoryStreamManager, you can choose between two strategies for the Large Pool to match your application's memory usage patterns:

• Linear (Default): You specify a multiple and a maximum size. The pool contains an array of buffers that grow linearly (e.g., 1MB, 2MB, 3MB... up to a maximum). This is suitable for unpredictable large buffer sizes.
• Exponential: Buffers double in size for each slot (e.g., 256KB, 512KB, 1MB, 2MB, 4MB, 8MB). This is more memory-efficient if you have many streams that are likely to stay within smaller size ranges.

When using this library in multi-threaded environments, observe the following rules:

• RecyclableMemoryStream: Concurrent use of individual stream objects is not supported under any circumstances.
• RecyclableMemoryStreamManager: This manager is thread-safe and can be used to retrieve streams across multiple threads safely.

The RecyclableMemoryStreamManager.Events class provides Event Tracing for Windows (ETW) events for RecyclableMemoryStream. You can use these events to monitor the lifecycle and performance of memory streams, such as buffer creation, disposal, and capacity issues.

All events are written through the static Writer property.

By default, for performance reasons, buffers are not pre-initialized or zeroed-out when recycled. It is the developer's responsibility to ensure that data from a previous use of a buffer does not leak into a new operation.

If your application requires protection against accidental data leakage, you can set ZeroOutBuffer to true. Note that this will incur a performance penalty as buffers will be zeroed out upon allocation and before being returned to the pool.

RecyclableMemoryStream is optimized for chained small pool blocks. Using methods that require contiguous memory can negate the benefits of the library:

• ToArray: Avoid this. It always copies data into a new, non-pooled array. Using ToArray is considered a bug in high-performance scenarios. You can configure RecyclableStreamManager.ThrowExceptionOnToArray = true to prevent its use.
• GetBuffer: If the stream uses multiple blocks, this method will copy them into a single large pool buffer. Always use the Length property to determine usable data size.

To help identify the source and lifetime of streams, RecyclableMemoryStream uses two identification mechanisms:

1. GUID: Each stream object is assigned a unique GUID that identifies it throughout its entire lifetime.
2. Tag: You can optionally assign an arbitrary string (a tag) when requesting a stream from the manager. This is useful for labeling streams with a class name or function name to track where in your code the stream originated. Note that tags are not unique; multiple streams can share the same tag.

These identifiers are included in ETW events to help you trace issues.

To use the library, instantiate a RecyclableMemoryStreamManager once and reuse it for the lifetime of your process. You can then request streams using manager.GetStream().

Important: RecyclableMemoryStreamManager should be a long-lived object (e.g., a static field) to ensure effective pooling.

class Program
{
    private static readonly RecyclableMemoryStreamManager manager = new RecyclableMemoryStreamManager();

    static void Main(string[] args)
    {
        var sourceBuffer = new byte[] { 0, 1, 2, 3, 4, 5, 6, 7 };
        
        using (var stream = manager.GetStream())
        {
            stream.Write(sourceBuffer, 0, sourceBuffer.Length);
        }
    }
}