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 the stack

  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::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

AUTHOR
    vividsnow

LICENSE
    Same terms as Perl itself.