Core.Buffers 1.0.29

Core.Buffers

A .NET library for efficient buffer management that provides thread-safe, modern, and fast buffer functionality currently missing in vanilla .NET.

Installation

dotnet add package Core.Buffers

Features

• DoubleBuffer<TEntity>: A double-buffering mechanism for unmanaged types, allowing for concurrent read and write operations.
• DoubleBufferQueue<TEntity>: A queue implementation built on top of a double buffer, allowing for concurrent enqueue operations while maintaining the ability to swap buffers atomically.

Usage

DoubleBuffer<TEntity>

The DoubleBuffer<TEntity> class provides a double-buffering mechanism that allows for concurrent read and write operations. This is particularly useful in scenarios where you need to write to a buffer while reading from another buffer.

using Core.Buffers;

// Create a double buffer with a size of 1024 elements * 2  ( double buffer )
using var buffer = new DoubleBuffer<int>(MemoryPool<int>.Shared, 1024);

// Write to the active buffer
for (int i = 0; i < buffer.Size; i++)
{
    buffer.Active.Span[i] = i;
}

// Swap buffers atomically and get the previous buffer as ReadOnlyMemory
ReadOnlyMemory<int> previousBuffer = buffer.Swap();

// Now you can read from the previous buffer while writing to the new active buffer
// The previousBuffer can be used directly for reading

// Write to the (next) active buffer
for (int i = 0; i < buffer.Size; i++)
{
    buffer.Active.Span[i] = i;
}

// You can also access the shadow (inactive) buffer
Console.WriteLine($"Active buffer offset: {buffer.ActiveOffset}");
Console.WriteLine($"Shadow buffer offset: {buffer.ShadowOffset}");

// Read from the shadow buffer (read-only)
for (int i = 0; i < buffer.Size; i++)
{
    Console.WriteLine(buffer.Shadow.Span[i]);
}

DoubleBufferQueue<TEntity>

The DoubleBufferQueue<TEntity> class extends the DoubleBuffer<TEntity> class to provide a queue implementation that allows for concurrent enqueue operations while maintaining the ability to swap buffers atomically.

using Core.Buffers;

// Create a double buffer queue with a size of 1024 elements * 2 ( double buffer )
using var queue = new DoubleBufferQueue<int>(MemoryPool<int>.Shared, 1024);

// Enqueue items to the active buffer
for (int i = 0; i < 100; i++)
{
    queue.Enqueue(i);
    // or 
    if (!queue.TryEnqueue(i)) break;


}

// Check if the queue is full
if (queue.Exhausted)
{
    Console.WriteLine("Queue is full!");
}

// Get the count of items in the active buffer
Console.WriteLine($"Items in queue: {queue.Count}");

// Swap buffers atomically and get the previous buffer as ReadOnlyMemory, with the lenght of the commited items
ReadOnlyMemory<int> previousBuffer = queue.Swap();

// Now you can process the items in the previous buffer
// while new items are being enqueued to the new active buffer
// The previousBuffer contains only the valid items (sliced to the count)

API Reference

DoubleBuffer<TEntity>

• Constructor: DoubleBuffer<TEntity>(MemoryPool<TEntity> memoryPool, int size)

  • Creates a new double buffer with the specified size.

• Properties:

  • Memory<TEntity> Active: Gets the currently active buffer, from the perspective of the writer.
  • ReadOnlyMemory<TEntity> Shadow: Gets the current shadow (inactive) buffer, from the perspective of the writer.
  • ReadOnlyMemory<TEntity> Raw: Gets the complete double buffer (primary+secondary) as ReadOnlyMemory.
  • int Size: Gets the size of each individual buffer.
  • int ActiveOffset: Gets the current offset for the Active buffer, from the perspective of the writer.
  • int ShadowOffset: Gets the current offset for the readonly Shadow buffer, from the perspective of the writer.

• Methods:

  • ReadOnlyMemory<TEntity> Swap(): Swaps the active/shadow buffers atomically and returns new Shadow buffer as a ReadOnlyMemory.
  • void Dispose(): Releases all resources used by the double buffer.

DoubleBufferQueue<TEntity>

• Constructor: DoubleBufferQueue<TEntity>(MemoryPool<TEntity> memoryPool, int size)

  • Creates a new double buffer queue with the specified size.

• Properties:

  • int Count: Gets the number of items in the currently active queue.
  • bool Exhausted: Gets a value indicating whether the current active buffer is full.

• Methods:

  • ReadOnlyMemory<TEntity> Swap(): Swaps the active/shadow buffers atomically and returns new Shadow buffer as a ReadOnlyMemory, sliced to contain only the valid items.
  • ref TEntity Next(): Gets a reference to the next available position in the active buffer and increments the count.
  • void Enqueue(TEntity value): Adds an item to the end of the queue in the active buffer.
  • bool TryEnqueue(TEntity value): Tries to add an item to the end of the queue in the active buffer, returning false if the buffer is full.

Requirements

• .NET 7.0, .NET 8.0, or .NET 9.0

License

This project is licensed under the MIT License - see the LICENSE file for details.