/ 
Data-Heap-Shared-0.02
/ Data::Heap::Shared

NAME

Data::Heap::Shared - Shared-memory binary min-heap (priority queue) for Linux

SYNOPSIS

use Data::Heap::Shared;

my $heap = Data::Heap::Shared->new(undef, 1000);
$heap->push(3, 300);   # priority=3, value=300
$heap->push(1, 100);
$heap->push(2, 200);

my ($pri, $val) = $heap->pop;   # (1, 100) — lowest priority first
my ($pri, $val) = $heap->peek;  # (2, 200) — without removing

# blocking pop
my ($pri, $val) = $heap->pop_wait(5.0);

DESCRIPTION

Binary min-heap in shared memory. Elements are (priority, value) integer pairs. Lowest priority pops first.

Mutex-protected push/pop with sift-up/sift-down. PID-based stale mutex recovery. Futex blocking when empty.

Crash safety: if a process dies while holding the heap mutex (mid-push or mid-pop), the mutex is recovered via PID detection, but the heap data may be in an inconsistent state (partially sifted). Callers should clear and rebuild if crash recovery is triggered in a critical application.

Linux-only. Requires 64-bit Perl.

METHODS

$heap->push($priority, $value);          # returns bool
my ($pri, $val) = $heap->pop;            # returns () if empty
my ($pri, $val) = $heap->pop_wait;       # blocking
my ($pri, $val) = $heap->pop_wait($t);   # with timeout
my ($pri, $val) = $heap->peek;           # without removing

$heap->size;  $heap->capacity;  $heap->is_empty;  $heap->is_full;
$heap->clear;  $heap->stats;  $heap->path;  $heap->memfd;
$heap->sync;   $heap->unlink;

# constructors
$heap = Data::Heap::Shared->new_memfd($name, $capacity);
$heap = Data::Heap::Shared->new_from_fd($fd);

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

STATS

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

BENCHMARKS

Single-process (500K ops, x86_64 Linux, Perl 5.40):

push (sequential)       5.3M/s
pop (drain)             2.5M/s
push+pop (interleaved)  2.5M/s
peek                    4.9M/s

Multi-process (4 workers, 100K ops each, cap=64):

push+pop                3.1M/s aggregate

SECURITY

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

SEE ALSO

Data::Stack::Shared - LIFO stack

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

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::Graph::Shared - directed weighted graph

AUTHOR

vividsnow

LICENSE

Same terms as Perl itself.