[WIP]Update README

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`