Awesome

K4os.Streams

Description

The need for this library was triggered by a project which used MemoryStream a lot and I was told by memory profiler that is very heavy on memory allocation.

I was aware that RecyclableMemoryStream exists but I wanted something lighter (the question if I succeeded is a different matter, lol).

There are two (so far) stream implementations in this library: ResizingByteBufferStream and ChunkedByteBufferStream. Both of them are using ArrayPool<byte> but ResizingByteBufferStream stores data in one (potentially) large array (the same approach as MemoryStream) while ChunkedByteBufferStream stores data in a list of chunks.

Measuring performance

Measuring performance if form of magic and it is very hard to get objective numbers.

It is hard to measure performance, because lot of it depends on usage patterns.

Are you using small or large streams? Do they stay in memory for long? Do you read/write them in small or large chunks? What are the thresholds for certain actions (like resizing or chunking)? Do you measure it just before threshold or just after?

Let's say we measure a data structure which rebuilds itself around 1024 elements. You measure performance at 1023 and it might the best, you measure at 1025 and it is 20% behind all other competitors.

What I measured was continuous writing (no Seek) of small chunks (1K) and then continuous reading but in bigger chunks (8K). This was based on usage pattern where I was building a json payload from data (small Writes) and then sending them over network (bigger Reads).

Note, I think I already notices that RecyclableMemoryStream prefer larger chunks, so YMMV.

All measurements were done using:

BenchmarkDotNet=v0.13.5, OS=Windows 11 (10.0.22621.1848/22H2/2022Update/SunValley2)
AMD Ryzen 5 3600, 1 CPU, 12 logical and 6 physical cores
.NET SDK=6.0.410
  [Host]     : .NET 6.0.18 (6.0.1823.26907), X64 RyuJIT AVX2
  DefaultJob : .NET 6.0.18 (6.0.1823.26907), X64 RyuJIT AVX2

NOTE: in first column names of streams has been shortened to fit in table:

Small streams (128B - 64KB)

Medium streams (128KB - 8MB)

Large streams (128MB - 512MB)

Observations

• ResizingByteBufferStream is the fastest for small streams
• ChunkedByteBufferStream is not much worse in small stream range, but shines in medium and large streams
• RecyclableMemoryStream has quite a lot of overhead, that's why it's 5x slower than MemoryStream for tiny streams
• RecyclableMemoryStream is very good for medium and large stream
• MemoryStream is the kind of good for tiny streams, but nothing more
• MemoryStream is the worst for large streams
• RecyclableMemoryStream has an interesting top performance at 64K - 128K range and will investigate it further
• I think, it means that transition between small and medium stream could be improved in ChunkedByteBufferStream

Decision tree

I just roughly scored choosing given stream implementations for certain ranges:

What I would say, the result can be read as: ResizingByteBufferStream is the best for small streams, while ChunkedByteBufferStream is the best all-rounder. MemoryStream is terrible for large streams, while RecyclableMemoryStream is quite bad for small streams.

• If your streams are always very small, use ResizingByteBufferStream
• If your streams are always quite large, use RecyclableMemoryStream or ChunkedByteBufferStream
• If you need a compromise, have medium or unpredictable sizes, use ChunkedByteBufferStream

Usage

One very important note is those streams need to be disposed to get the benefit, if you don't dispose them the performance will be roughly the same as MemoryStream.

It is a little bit problematic though as memory is disposed at Dispose so you may not access it .ToArray() after that.

If you need to get data from stream, do it before disposing it!

using var stream = new ChunkedByteBufferStream();
using var writer = new StreamWriter(stream, leaveOpen: true); // NOTE: leaveOpen!
writer.Write("Hello, world!");
writer.Flush();
Console.WriteLine(Encoding.UTF8.GetString(stream.ToArray());

There are some memory specific methods available on both streams allowing quickly access data in them:

class ResizingByteBufferStream: Stream
{
    Span<byte> AsSpan();
    
    int ExportTo(Span<byte> target);
    byte[] ToArray();
}

class ChunkedByteBufferStream: Stream
{
    int ExportTo(Span<byte> target);
    byte[] ToArray();
}

(NOTE: no AsSpan() for ChunkedByteBufferStream because it is not a single block of memory, I may add AsReadOnlySequence one day though).

Other than that it is just a Stream.

Build

build