KZDev.PerfUtils 3.0.1

KZDev.PerfUtils

The KZDev.PerfUtils package provides the following high-performance utility classes:

• MemoryStreamSlim: A high-performance, memory-efficient stream for large or frequently resized in-memory buffers, modeled on MemoryStream with a largely compatible API.
• StringBuilderCache: A thread-safe cache of StringBuilder instances to improve speed and reduce the overhead of memory allocations associated with the StringBuilder class.
• InterlockedOps: A utility that extends the functionality of the Interlocked class in the .NET Class Library by providing additional atomic thread-safe operations.

Important: MemoryStreamSlim outperforms RecyclableMemoryStream across all benchmarked categories in this project.

New in v3: MemoryStreamSlim.ToMemory() introduces a significantly more memory-efficient way to access raw stream buffers as Memory<byte>.

Supported target frameworks

This package targets .NET 8 (net8.0), .NET 9 (net9.0), and .NET 10 (net10.0). The 3.x line does not ship builds for older TFMs (including .NET 6); upgrade consuming projects to a supported target framework before referencing the latest package versions.

Performance Highlights

This sampling of performance benchmarks clearly demonstrates the advantages of using the KZDev.PerfUtils package:

For more details, refer to the benchmark related pages in the documentation.

Features

MemoryStreamSlim

MemoryStreamSlim targets workloads where MemoryStream limits throughput or drives high GC cost. It is largely API-compatible with MemoryStream, so many call sites can switch the concrete type with small edits, but it is not guaranteed to match MemoryStream in every behavioral edge case. Construct instances with MemoryStreamSlim.Create (and related overloads) instead of new MemoryStream. After Dispose, Length, Position, and capacity-related members follow the same ObjectDisposedException rules as MemoryStream; do not rely on reading those values from a disposed stream.

• Improved Throughput: Outperforms the standard MemoryStream.
• Reduced Memory Traffic: Significantly lowers memory traffic and garbage collection compared to the standard MemoryStream.
• Eliminates LOH Fragmentation: Prevents Large Object Heap (LOH) fragmentation caused by frequent use and release of single-byte arrays.
• Optional Native Memory Storage: Allows the use of native memory for storage, further reducing GC pressure and increasing flexibility.
• Outperforms Similar Libraries: Compared to other libraries like RecyclableMemoryStream, it is designed to be easier to use, more flexible, and incurs fewer memory allocations and garbage collections.

StringBuilderCache

StringBuilderCache is a static class that provides a thread-safe cache of StringBuilder instances, reducing allocations and deallocations in high-throughput scenarios. Key features include:

• Acquire: Retrieve a StringBuilder instance from the cache.
• Release: Return a StringBuilder instance to the cache.
• GetStringAndRelease: Retrieve the string from a StringBuilder instance and return it to the cache.
• GetScope: Use a using-scoped StringBuilder instance, which is automatically returned to the cache when the scope is exited.
• Monitoring: Leverages the .NET runtime's Events feature for detailed cache management and monitoring.

InterlockedOps

InterlockedOps is a static class that provides additional thread-safe atomic operations for integer types, including:

• Xor: Perform an exclusive OR operation.
• ClearBits: Clear specific bits.
• SetBits: Set specific bits.
• ConditionAnd: Conditionally update bits using an AND operation.
• ConditionOr: Conditionally update bits using an OR operation.
• ConditionXor: Conditionally update bits using an XOR operation.
• ConditionClearBits: Conditionally clear specific bits.
• ConditionSetBits: Conditionally set specific bits.

Examples

MemoryStreamSlim Example

Below is an example of how to use the MemoryStreamSlim class. Use the Create methods for construction; the member surface area matches MemoryStream for supported APIs, with behavioral differences documented for disposed streams and advanced options. Dispose the MemoryStreamSlim instance when it is no longer needed.

using KZDev.PerfUtils;

// Create a new MemoryStreamSlim instance
// For the best management of the memory buffers, it is very important to
// dispose of the MemoryStreamSlim instance when it is no longer needed.
using (MemoryStreamSlim stream = MemoryStreamSlim.Create())
{
        // Write some data to the stream
        stream.Write(new byte[] { 1, 2, 3, 4, 5 }, 0, 5);

        // Read the data back from the stream
        stream.Position = 0;
        byte[] buffer = new byte[5];
        stream.Read(buffer, 0, 5);
}

StringBuilderCache Example

Below is an example of how to use the StringBuilderCache class to acquire a StringBuilder instance, append strings to it, and then release it back to the cache. The GetStringAndRelease method is used to retrieve the string and release the StringBuilder instance back to the cache.

using KZDev.PerfUtils;

class Program
{
    static void Main()
    {
        StringBuilder stringBuilder = StringBuilderCache.Acquire();
        stringBuilder.Append("Hello, ");
        stringBuilder.Append("World!");
        Console.WriteLine(StringBuilderCache.GetStringAndRelease(stringBuilder));
    }
}

InterlockedOps Example

Below is an example of how to use the InterlockedOps class to perform an atomic XOR operation on an integer variable. The Xor method toggles a bit flag between 1 and 0 in a thread-safe manner and returns a boolean value indicating whether the bit flag was set to 1.

using KZDev.PerfUtils;

public class XorExample
{
    private int _flag;

    public bool ToggleFlag ()
    {
        int originalValue = InterlockedOps.Xor(ref _flag, 1);
        return originalValue == 0;
    }
}

Compare to RecyclableMemoryStream

The MemoryStreamSlim class is conceptually similar to the RecyclableMemoryStream class from Microsoft. However, the internal implementation of buffer management is quite different. Compared to RecyclableMemoryStream, the MemoryStreamSlim class is designed to:

• Easier to use without requiring parameter tuning.
• More flexible across a broad range of use cases.
• Fewer memory allocations and garbage collections.
• Consistent performance across workloads.
• Security-first design with opt-out zeroing of unused memory.
• Automatic memory trimming and release.
• Supports .NET Metrics and Events for monitoring.
• Optionally uses native memory to avoid GC pressure.

Performance comparisons are also available in the benchmarks documentation section.

Documentation

Comprehensive documentation for the package is available on the PerfUtils Documentation page.

Future Features

The roadmap for this package includes plans to add additional performance-focused utilities as time permits.