PerfUtils
The KZDev.PerfUtils
package contains the following performance utility classes:
MemoryStreamSlim
- a high-performance, memory-efficient, easy-to-use replacement for theMemoryStream
class that provides particular performance benefits for large or frequently used streams.StringBuilderCache
- a thread-safe cache ofStringBuilder
instances to improve speed and reduce the overhead of memory allocations associated with using theStringBuilder
class.InterlockedOps
- which provides additional atomic thread-safe operations to extend the functionality of theInterlocked
class in the .NET Class Library.
See the individual documentation pages and the API Reference for more detailed information.
Features
MemoryStreamSlim
is a drop-in replacement for the MemoryStream
class used for dynamically sized streams that provides the following benefits:
- Throughput performance is better than the standard
MemoryStream
. - Much lower memory traffic and far fewer garbage collections than the standard
MemoryStream
. - Eliminates Large Object Heap (LOH) fragmentation caused by frequent use and release of various sized byte arrays used by the standard
MemoryStream
. - Simple replacement for
MemoryStream
with the same API, other than the constructor. - Optionally allows using native memory for storage, which allows even more flexibility to minimize GC pressure.
- Monitoring with
Metrics
andEvents
features of the .NET runtime.
StringBuilderCache
is a static class that provides a thread-safe cache of StringBuilder
instances to reduce the number of allocations and deallocations of StringBuilder
objects in high-throughput scenarios with simple operations:
- Acquire : Get a
StringBuilder
instance from the cache. - Release : Return a
StringBuilder
instance to the cache. - GetStringAndRelease : Get the string from a
StringBuilder
instance and return it to the cache. - GetScope : Get a
using
scopedStringBuilder
instance from the cache and return it to the cache when the scope is exited. - Monitoring with
Events
feature of the .NET runtime for detailed cache management.
InterlockedOps
is a static class providing the following thread-safe atomic operations:
- Xor : Exclusive OR operation on any integer types.
- ClearBits : Clear bits on any integer types.
- SetBits : Set bits on any integer types.
- ConditionAnd : Conditionally update bits using an AND operation on any integer types.
- ConditionOr : Conditionally update bits using an OR operation on any integer types.
- ConditionXor : Conditionally update bits using an XOR operation on any integer types.
- ConditionClearBits : Conditionally clear bits on any integer types.
- ConditionSetBits : Conditionally set bits on any integer types.
StringBuilderCache Example
Below is an example of how to use the StringBuilderCache
class to reduce the number of allocations and deallocations of StringBuilder
objects in high-throughput scenarios. The GetStringAndRelease
method is used to get the string from a StringBuilder
instance and return it to the cache.
using KZDev.PerfUtils;
public class StringBuilderExample
{
public static void GetStringAndRelease ()
{
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 is used to toggle a bit flag between 1
and 0
in a thread-safe manner and returns a boolean value indicating if 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;
}
}
MemoryStreamSlim Example
Below is an example of how to use the MemoryStreamSlim
class. Other than instantiation using the Create
method, the API is identical to the standard MemoryStream
class. It is always a best practice to dispose of 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);
}
Compare to RecyclableMemoryStream
The MemoryStreamSlim
class is similar in concept and purpose to the RecyclableMemoryStream
class from Microsoft however the internal implementation of buffer management is quite different. Also, compared to RecyclableMemoryStream
, the MemoryStreamSlim
class is designed to:
- 'Just work' and be easier to use without tuning parameters.
- Be more flexible in most use cases.
- Perform fewer memory allocations.
- Incur fewer garbage collections.
- Perform on par or better in terms of throughput performance.
- Provide more consistent performance across different workloads.
- Treat security as a priority and opt-out rather than opt-in zero'ing unused memory.
- Automatically trim and release extra memory when possible.
- Monitoring available through .NET counter
Metrics
as well asEvents
. - Optionally allow using native memory for storage to avoid GC pressure altogether.
One other important difference is that MemoryStreamSlim
is specifically designed to be used for dynamically sized memory streams and not as a Stream
wrapper around existing in-memory byte arrays. RecyclableMemoryStream
is designed to be used in both scenarios, but that approach can lead to some significant performance issues and non-deterministic behaviors. This is covered more in the full documentation. Performance comparisons are also available in the Benchmarks section.
Documentation
Full documentation for the package is available on the PerfUtils Documentation page.
Future Features
The roadmap plan for this package is to add a number of additional helpful performance focused utilities. These will be forthcoming as time permits.