Welcome to RingBufferPlus

The generic ring buffer with auto-scaler (elastic buffer).

RingBufferPlus is a bounded, thread-safe pool of reusable instances of T — built once via a factory you supply, acquired and returned by callers — with an optional elastic capacity that scales up and down at runtime, manually or automatically, to keep resource usage matched to demand instead of provisioning for the worst case.

What's new in the latest version

Full version history has moved to CHANGELOG.md.

v5.0.0 (latest released version) is a complete, coordinated product overhaul with sweeping breaking changes — see the ADRs and the CHANGELOG's "Breaking changes v5.0.0" section (the sole migration reference — no separate migration guide is provided) for full context. v4.x no longer receives fixes now that v5.0.0 has shipped.

Installing

dotnet add package RingBufferPlus [--prerelease]

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

Quickstart

Random rnd = new();

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();

For elastic (scaling) buffers, 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
• Elastic capacity with manual scale
• Elastic capacity with autoscale on acquire fault
• Locking SwitchToAsync while scaling
• HeartBeat
• Background logger
• 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 with manual scale.
• RingBufferPlusApiSample — elastic capacity with manual scale in an ASP.NET Core API.
• RingBufferPlusBasicTriggerScale — elastic capacity with autoscale on acquire fault.
• RingBufferPlusRabbitSample — RabbitMQ channel pooling with autoscale.

API Reference

Generated per-type/per-member reference: src/docs/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.