RingBufferPlus

Stop provisioning for worst case. Pool it, scale it, let it breathe.

RingBufferPlus is a bounded, thread-safe pool for any expensive-to-create resource — database connections, RabbitMQ channels, HTTP clients, whatever your Factory builds. You get one back with AcquireAsync, you return it by disposing it, and the pool takes care of keeping enough of them around without you having to guess a number up front.

Why RingBufferPlus

• Elastic capacity, on by default. An elastic pool grows the instant callers are genuinely waiting, and shrinks predictively as demand trends down — no cron job, no manual tuning required to get useful behavior.
• Three signals, one owner. A floor guard, a backlog-reactive signal, and a predictive Monitor all watch the pool; a single-consumer engine arbitrates between them so capacity never races itself.
• Manual override when you need it. SwitchToAsync pins the pool to a capacity for a set duration — the automatic signals keep running underneath, they just take a back seat.
• Native observability, zero extra dependency. Metrics and traces via the .NET-shipped Meter/ActivitySource — plug in any OpenTelemetry exporter, nothing extra to install.
• Health checks built in. HeartBeat inspects a live item on a schedule and replaces it automatically if it's gone bad — no separate watchdog to write.
• Async all the way down. IAsyncDisposable throughout; no sync-over-async traps.
• .NET 8, 9, and 10 — one package, three target frameworks.

What's new in the latest version

Full version history has moved to CHANGELOG.md.

v6.0.0 (latest released version) is a complete, coordinated product overhaul with sweeping breaking changes to the concurrency model, autoscale algorithm, and public fluent API surface — see the ADRs and the CHANGELOG's "Breaking changes" section for v6.0.0 (the sole migration reference — no separate migration guide is provided). v5.x no longer receives fixes now that v6.0.0 has shipped.

Every v6.0.0 change went through a 12-round adversarial pre-release audit before shipping — see the audit report for the method and what it found.

Installing

dotnet add package RingBufferPlus [--prerelease]

Note: [--prerelease] for pre-release versions.

Quickstart

A fixed pool, for when you know your capacity up front:

Random rnd = new();
CancellationToken cancellation = default;

var rb = await RingBuffer<int>.New("MyBuffer")
    .Factory((_) => Task.FromResult(rnd.Next(1, 10)))
    .FixedCapacity(3)
    .BuildWarmupAsync(cancellation);

await using (var buffer = await rb.AcquireAsync(cancellation))
{
    if (buffer.Successful)
    {
        Console.WriteLine($"value: {buffer.Current}, elapsed: {buffer.ElapsedTime}");
    }
}

await rb.DisposeAsync();

An elastic pool, for when demand varies and you'd rather not guess:

var rb = await RingBuffer<int>.New("MyBuffer")
    .Factory((_) => Task.FromResult(rnd.Next(1, 10)))
    .ElasticCapacity(minCapacity: 2, maxCapacity: 10, target: 4)
    .BuildWarmupAsync(cancellation);

// No further setup needed - the floor guard, backlog-reactive signal, and
// predictive Monitor are already watching this pool.

For dependency injection, RabbitMQ channel pooling, and every other builder option, see the guides below.

Guides

• Concepts — the mental model: lifecycle, Capacity/MinCapacity/MaxCapacity, thread-safety, when not to use this library.
• Fixed capacity
• Pinning capacity manually
• Elastic autoscale
• Locking SwitchToAsync while scaling
• HeartBeat
• RabbitMQ channel pooling
• ASP.NET Core / generic host dependency injection
• Observability (metrics and tracing)

Examples

For runnable samples, see the Samples directory:

• RingBufferPlusBasicSample — fixed capacity with HeartBeat.
• RingBufferPlusBasicManualScale — elastic capacity, pinning capacity manually.
• RingBufferPlusApiSample — elastic capacity, pinning capacity manually, in an ASP.NET Core API.
• RingBufferPlusBasicTriggerScale — elastic capacity with autoscale.
• RingBufferPlusRabbitSample — RabbitMQ channel pooling with autoscale.

API Reference

Generated per-type/per-member reference: doc/api/docindex.md.

Architecture Decision Records (ADR)

RingBufferPlus documents its significant architectural and design decisions as Architecture Decision Records (ADR), following the AdrPlus convention. Each record captures the context, the decision, the alternatives considered, and the consequences — so the reasoning behind the library's design stays traceable over time.

👉 See the ADR index for the full list of decisions.

Code of Conduct

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the Code of Conduct.

Contributing

See the Contributing guide for developer documentation, and the Architecture overview for a map of the main components before you dive into the source.

Security

To report a (suspected) security vulnerability, see SECURITY.md.

Credits

This work was inspired by Luiz Carlos Faria project.

API documentation generated by

• XmlDocMarkdown, Copyright (c) 2024 Ed Ball
  • See an unrefined customization to contain header and other adjustments in project XmlDocMarkdownGenerator

License

Copyright 2022 @ Fernando Cerqueira

RingBufferPlus is licensed under the MIT license. See LICENSE.