/ 
Data-Stack-Shared-0.02
/ Data::Stack::Shared

NAME

Data::Stack::Shared - Shared-memory LIFO stack for Linux

SYNOPSIS

use Data::Stack::Shared;

my $stk = Data::Stack::Shared::Int->new(undef, 100);
$stk->push(42);
$stk->push(99);
say $stk->pop;       # 99 (LIFO)
say $stk->peek;      # 42
say $stk->size;      # 1

# blocking with timeout
$stk->push_wait(42, 5.0);
my $val = $stk->pop_wait(5.0);

# string variant
my $ss = Data::Stack::Shared::Str->new(undef, 50, 256);
$ss->push("hello");
say $ss->pop;

# anonymous / memfd / file-backed
my $s = Data::Stack::Shared::Int->new('/tmp/stk.shm', 100);
$s = Data::Stack::Shared::Int->new(undef, 100);
$s = Data::Stack::Shared::Int->new_memfd("my_stk", 100);
my $fd = $s->memfd;
$s = Data::Stack::Shared::Int->new_from_fd($fd);

DESCRIPTION

LIFO stack in shared memory. CAS-based lock-free push/pop on an atomic top index. Futex blocking when empty or full.

Linux-only. Requires 64-bit Perl.

Variants

Data::Stack::Shared::Int - int64_t values
Data::Stack::Shared::Str - fixed-length strings

METHODS

Push / Pop

my $ok  = $stk->push($val);               # non-blocking
$ok     = $stk->push_wait($val);           # blocking (infinite)
$ok     = $stk->push_wait($val, $timeout); # blocking with timeout

my $val = $stk->pop;                       # non-blocking, undef if empty
$val    = $stk->pop_wait;                  # blocking (infinite)
$val    = $stk->pop_wait($timeout);        # blocking with timeout

$val    = $stk->peek;                      # read top without removing

Status

my $n   = $stk->size;
my $cap = $stk->capacity;
my $ok  = $stk->is_empty;
my $ok  = $stk->is_full;
$stk->clear;                               # empty (NOT concurrency-safe)
my $n = $stk->drain;                       # empty (concurrency-safe, returns count)

Common

my $p  = $stk->path;
my $fd = $stk->memfd;
$stk->sync;
$stk->unlink;
my $s  = $stk->stats;

eventfd

my $fd = $stk->eventfd;
$stk->eventfd_set($fd);
my $fd = $stk->fileno;
$stk->notify;
my $n  = $stk->eventfd_consume;

STATS

stats() returns: size, capacity, pushes, pops, waits, timeouts, mmap_size.

SECURITY

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

BENCHMARKS

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

Int push + pop          6.4M/s
Int push (fill) + pop   6.4M/s
Int peek               13.0M/s
Str push + pop (48B)    4.7M/s

Multi-process (8 workers, 200K ops each, cap=64):

Int push + pop          5.0M/s aggregate

SEE ALSO

Data::Deque::Shared - double-ended queue (deque)

Data::Queue::Shared - FIFO queue

Data::ReqRep::Shared - request-reply

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

Data::Log::Shared - append-only log (WAL)

Data::Buffer::Shared - typed shared array

Data::Sync::Shared - synchronization primitives

Data::HashMap::Shared - concurrent hash table

Data::PubSub::Shared - publish-subscribe ring

Data::Heap::Shared - priority queue

Data::Graph::Shared - directed weighted graph

AUTHOR

vividsnow

LICENSE

Same terms as Perl itself.