ring-buffer-macro

A procedural macro for creating ring buffer (circular buffer) data structures at compile time

Documentation | Crates.io | Repository

---

Overview

A ring buffer is a fixed-size FIFO (First-In-First-Out) data structure that efficiently reuses memory by wrapping around when it reaches the end. This macro generates all necessary fields and methods at compile time with zero runtime overhead.

Features

• Zero runtime overhead - All code generation happens at compile time
• Type safe - Works with any type implementing Clone
• Generic support - Preserves type parameters and constraints
• Visibility preservation - Maintains your struct's visibility modifiers
• Comprehensive API - All standard ring buffer operations

Installation

Add this to your Cargo.toml:

[dependencies]
ring-buffer-macro = "0.1.0"

Quick Start

use ring_buffer_macro::ring_buffer;

#[ring_buffer(5)]
struct IntBuffer {
    data: Vec<i32>,
}

fn main() {
    let mut buf = IntBuffer::new();

    buf.enqueue(1).unwrap();
    buf.enqueue(2).unwrap();
    buf.enqueue(3).unwrap();

    assert_eq!(buf.dequeue(), Some(1));
    assert_eq!(buf.dequeue(), Some(2));
    assert_eq!(buf.len(), 1);
}

How It Works

The #[ring_buffer(capacity)] attribute macro transforms your struct:

Input

#[ring_buffer(5)]
struct Buffer {
    data: Vec<i32>,
}

Output

Adds fields:

• capacity: usize - Maximum elements
• head: usize - Read position
• tail: usize - Write position
• size: usize - Current count

Generates methods:

• new() - Creates empty buffer
• enqueue(item) - Adds item, returns Err(item) if full
• dequeue() - Removes oldest item (requires T: Clone)
• is_full() - Checks if at capacity
• is_empty() - Checks if empty
• len() - Current element count
• capacity() - Maximum capacity
• clear() - Removes all elements

Requirements

• Struct with named fields
• Field named data of type Vec<T>
• Element type T must implement Clone
• Capacity must be positive integer literal

Performance

• O(1) enqueue and dequeue operations
• Zero allocations after initialization
• No runtime overhead - everything generated at compile time
• Cache-friendly - contiguous memory access

Use Cases

• Logging systems with fixed-size buffers
• Audio/video sample buffers
• Network packet queues
• Embedded systems with constrained resources
• Rate limiting request queues
• Producer-consumer patterns

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

Licensed under the MIT License. See LICENSE for details.

---

Built with Rust