/ 
Data-RingBuffer-Shared-0.01
/ Data::RingBuffer::Shared

NAME

Data::RingBuffer::Shared - Shared-memory fixed-size ring buffer for Linux

SYNOPSIS

use Data::RingBuffer::Shared;

my $ring = Data::RingBuffer::Shared::Int->new(undef, 100);
$ring->write(42);
$ring->write(99);
say $ring->latest;        # 99 (most recent)
say $ring->latest(1);     # 42 (previous)
say $ring->size;          # 2

# overwrites oldest when full — never blocks
$ring->write($_) for 1..200;
say $ring->size;          # 100 (capacity)
say $ring->latest;        # 200

# read by sequence number
my $seq = $ring->write(777);
say $ring->read_seq($seq);  # 777

# wait for new data
my $cnt = $ring->count;
$ring->wait_for($cnt, 5.0);

# F64 variant
my $f = Data::RingBuffer::Shared::F64->new(undef, 1000);
$f->write(3.14);

# dump entire ring as list (oldest first)
my @vals = $ring->to_list;

DESCRIPTION

Fixed-size circular buffer in shared memory. Writes overwrite the oldest entry when the buffer is full — writes never block or fail. Readers access data by relative position (0=latest) or absolute sequence number.

Unlike Data::Queue::Shared (consumed on read, blocks when full) and Data::PubSub::Shared (subscription tracking), RingBuffer is a simple overwriting window with no consumer state.

Useful for metrics rings, sensor data, rolling windows, debug traces.

Linux-only. Requires 64-bit Perl.

Variants

Data::RingBuffer::Shared::Int - int64_t values
Data::RingBuffer::Shared::F64 - double values

METHODS

Constructors

$r = Data::RingBuffer::Shared::Int->new($path, $capacity);
$r = Data::RingBuffer::Shared::Int->new(undef, $capacity);
$r = Data::RingBuffer::Shared::Int->new_memfd($name, $cap);
$r = Data::RingBuffer::Shared::Int->new_from_fd($fd);

Write

my $seq = $ring->write($value);  # returns sequence number

Always succeeds. Overwrites oldest when full.

Read

my $val = $ring->latest;       # most recent (undef if empty)
my $val = $ring->latest($n);   # nth most recent (0=latest)
my $val = $ring->read_seq($s); # by sequence (undef if overwritten)

my @all = $ring->to_list;      # entire ring, oldest first

Status

$ring->size;       # entries in buffer (max = capacity)
$ring->capacity;
$ring->head;       # next write position (monotonic)
$ring->count;      # total writes (for wait_for)

Waiting

my $ok = $ring->wait_for($expected_count);          # block until count changes
my $ok = $ring->wait_for($expected_count, $timeout);

Returns 1 if new data arrived (count != expected), 0 on timeout.

Lifecycle

$ring->clear;      # reset head/count (NOT concurrency-safe)
$ring->sync;  $ring->unlink;  $ring->path;  $ring->memfd;
$ring->stats;

eventfd

$ring->eventfd;  $ring->eventfd_set($fd);  $ring->fileno;
$ring->notify;   $ring->eventfd_consume;

BENCHMARKS

Single-process (1M ops, x86_64 Linux, Perl 5.40, cap=1000):

Int write       11.7M/s
Int latest      11.1M/s
Int read_seq    10.4M/s
F64 write        8.8M/s
F64 latest      12.0M/s

STATS

stats() returns a hashref: size, capacity, head, count, writes, overwrites, mmap_size.

SECURITY

The mmap region is writable by all processes that open it. Do not share backing files with untrusted processes.

SEE ALSO

Data::Queue::Shared - FIFO queue (consumed on read)

Data::PubSub::Shared - publish-subscribe ring (subscription tracking)

Data::Buffer::Shared - typed shared array

Data::BitSet::Shared - shared bitset

Data::Pool::Shared - fixed-size object pool

Data::Stack::Shared - LIFO stack

Data::Deque::Shared - double-ended queue

Data::Log::Shared - append-only log

Data::Heap::Shared - priority queue

Data::Graph::Shared - directed weighted graph

Data::Sync::Shared - synchronization primitives

Data::HashMap::Shared - concurrent hash table

Data::ReqRep::Shared - request-reply

AUTHOR

vividsnow

LICENSE

Same terms as Perl itself.