Why Use a Lightweight Ring Buffer? Deep Dive into LwRB for Embedded Systems

Why a Ring Buffer?

Embedded systems often need to handle continuous data streams (e.g., UART, sensor data, network packets) within a fixed memory budget. A circular (ring) buffer stores data in a pre‑allocated array and reuses space as data is consumed, avoiding costly reallocations.

LwRB Overview

LwRB (Lightweight Ring Buffer) is a generic, open‑source C library for managing ring buffers. Repository: https://github.com/MaJerle/lwrb

Key Advantages

Zero dynamic allocation – operates entirely on static memory, eliminating fragmentation.

High performance – uses optimized memcpy instead of per‑byte loops.

Thread safety – relies on C11 atomic operations for single‑producer‑single‑consumer scenarios.

DMA friendly – supports zero‑copy operations for hardware DMA.

Core Principles

Ring Buffer Model

The buffer consists of a fixed‑size array buff of size S, a read pointer R, and a write pointer W. Rules:

When W == R the buffer is empty.

When W == (R‑1) % S the buffer is full.

Usable capacity is S‑1 bytes (one slot is reserved to distinguish empty from full).

Memory‑Safety Mechanism

Before writing, the library checks free space and aborts if the operation would overflow:

// Write‑side safety check
free = lwrb_get_free(buff);
if (free == 0 || (free < btw && (flags & LWRB_FLAG_WRITE_ALL))) {
    return 0; // prevent overflow
}
btw = BUF_MIN(free, btw); // limit write size

Thread‑Safety via C11 Atomics

Atomic loads and stores make pointer updates indivisible, eliminating data races without mutexes:

#define LWRB_LOAD(var, type) atomic_load_explicit(&(var), (type))
#define LWRB_STORE(var, val, type) atomic_store_explicit(&(var), (val), (type))

Key Code Structures

Core Data Structure

typedef struct lwrb {
    uint8_t *buff;          // data buffer
    lwrb_sz_t size;         // buffer size
    lwrb_sz_atomic_t r_ptr; // read pointer (atomic)
    lwrb_sz_atomic_t w_ptr; // write pointer (atomic)
    lwrb_evt_fn evt_fn;     // optional callback
    void *arg;              // user data
} lwrb_t;

Separate pointer and size – supports any buffer length.

Atomic pointers – ensure thread‑safe reads/writes.

Event callback – flexible notification mechanism.

Two‑Stage Write Strategy

The write operation first fills the linear part, then wraps around if needed, and finally updates the write pointer atomically:

// Stage 1: linear part
tocopy = BUF_MIN(buff->size - w_ptr, btw);
BUF_MEMCPY(&buff->buff[w_ptr], d_ptr, tocopy);
... // advance pointers
// Stage 2: wrap‑around
if (btw > 0) {
    BUF_MEMCPY(buff->buff, d_ptr, btw);
    w_ptr = btw;
}
// Stage 3: atomic update
LWRB_STORE(buff->w_ptr, w_ptr, memory_order_release);

Two‑Stage Read Strategy

// Stage 1: linear part
tocopy = BUF_MIN(buff->size - r_ptr, btr);
BUF_MEMCPY(d_ptr, &buff->buff[r_ptr], tocopy);
// Stage 2: wrap‑around
if (btr > 0) {
    BUF_MEMCPY(d_ptr, buff->buff, btr);
    r_ptr = btr;
}

Peek Function

Preview data without moving the read pointer:

lwrb_sz_t lwrb_peek(const lwrb_t *buff, lwrb_sz_t skip_count, void *data, lwrb_sz_t btp);

Examples

Minimal Example

#include <stdio.h>
#include <string.h>
#include "lwrb/lwrb.h"

int main(void) {
    lwrb_t buff = {0};
    uint8_t buf_data[8] = {0};
    lwrb_init(&buff, buf_data, sizeof(buf_data));
    lwrb_write(&buff, "0123", 4);
    printf("Bytes in buffer: %d
", (int)lwrb_get_full(&buff));
    uint8_t data[8] = {0};
    size_t len = lwrb_read(&buff, data, sizeof(data));
    printf("Read %zu bytes: %s
", len, data);
    return 0;
}

Ring Buffer vs Linear Buffer Overwrite

The demo shows that a circular buffer automatically overwrites the oldest data when full, whereas a naïve linear buffer either blocks or discards new writes.

Ring Buffer vs Message Queue

Both provide producer‑consumer decoupling but differ in data structure, flexibility, and overflow handling.

Data structure : Ring buffer uses a fixed‑size array with circular pointers; message queues typically use linked lists or dynamic arrays.

Data unit : Ring buffer stores a byte stream or fixed‑size block without inherent message boundaries; message queues store discrete messages with explicit boundaries.

Size flexibility : Ring buffer size is static; overflow is handled by overwrite or blocking. Message queues can grow dynamically or have a configurable maximum.

Priority support : Ring buffers are FIFO only; many message queues support priority ordering.

Overflow handling : Ring buffers may overwrite oldest data or return an error; message queues usually block the producer or return an error, never overwriting existing messages.

Memory efficiency : Ring buffers have no dynamic allocation and low overhead; message queues may incur fragmentation and higher overhead.

Typical use‑case : Ring buffers excel in high‑frequency continuous streams (audio, video, sensor data). Message queues are suited for structured inter‑process communication.

Summary

Ring buffers provide high performance and low memory usage, making them ideal for real‑time, high‑throughput embedded scenarios. They require manual handling of message boundaries.

Message queues offer greater flexibility, explicit message framing, and priority handling, suitable for complex IPC or service communication at the cost of higher memory overhead.