diff --git a/utils/buffer/README.md b/utils/buffer/README.md index 39ac180e23..a0c6ef3d95 100644 --- a/utils/buffer/README.md +++ b/utils/buffer/README.md @@ -1,3 +1,58 @@ +# `buffer_sv2` + +[![crates.io](https://img.shields.io/crates/v/buffer_sv2.svg)](https://crates.io/crates/buffer_sv2) +[![docs.rs](https://docs.rs/buffer_sv2/badge.svg)](https://docs.rs/buffer_sv2) +[![rustc+](https://img.shields.io/badge/rustc-1.75.0%2B-lightgrey.svg)](https://blog.rust-lang.org/2023/12/28/Rust-1.75.0.html) +[![license](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://github.com/stratum-mining/stratum/blob/main/LICENSE.md) +[![codecov](https://codecov.io/gh/stratum-mining/stratum/branch/main/graph/badge.svg?flag=buffer_sv2-coverage)](https://codecov.io/gh/stratum-mining/stratum) + +`buffer_sv2` handles memory management for Stratum v2 (Sv2) roles. It provides a memory-efficient +buffer pool that minimizes allocations and deallocations for high-throughput message frame +processing in Sv2 roles. Memory allocation overhead is minimized by reusing large buffers, +improving performance and reducing latency. The buffer pool tracks the usage of memory slices, +using atomic operations and shared state tracking to safely manage memory across multiple threads. + +## Main Components + +- **BufferPool**: A thread-safe pool of reusable memory buffers for high-throughput applications. +- **BufferFromSystemMemory**: Manages a dynamically growing buffer in system memory for applications + where performance is not a concern. +- **Slice**: A contiguous block of memory, either preallocated or dynamically allocated. + +## Usage + +To include this crate in your project, run: + +```bash +cargo add buffer_sv2 +``` + +This crate can be built with the following feature flags: + +- `debug`: Provides additional tracking for debugging memory management issues. +- `fuzz`: Enables support for fuzz testing. +- `with_serde`: builds [`binary_sv2`](https://crates.io/crates/binary_sv2) and + [`buffer_sv2`](https://crates.io/crates/buffer_sv2) crates with `serde`-based encoding and + decoding. Note that this feature flag is only used for the Message Generator, and deprecated + for any other kind of usage. It will likely be fully deprecated in the future. + +### Examples + +This crate provides four examples demonstrating how the memory is managed: + +1. **[Basic Usage Example](https://github.com/stratum-mining/stratum/blob/main/protocols/v2/codec-sv2/examples/basic_buffer_pool.rs)**: + Creates a buffer pool, writes to it, and retrieves the data from it. + +2. **[Buffer Pool Exhaustion Example](https://github.com/stratum-mining/stratum/blob/main/protocols/v2/codec-sv2/examples/buffer_pool_exhaustion.rs)**: + Demonstrates how data is added to a buffer pool and dynamically allocates directly to the heap + once the buffer pool's capacity has been exhausted. + +3. **[Variable Sized Messages Example](https://github.com/stratum-mining/stratum/blob/main/protocols/v2/codec-sv2/examples/variable_sized_messages.rs)**: + Writes messages of variable sizes to the buffer pool. + +3. **[Multi Threaded Example](https://github.com/stratum-mining/stratum/blob/main/protocols/v2/codec-sv2/examples/multi_threaded_buffer_pool.rs)**: + Writes to the buffer pool in a multi-threaded context. + # BufferPool This crate provides a `Write` trait used to replace `std::io::Write` in a non_std environment a `Buffer`