view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        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.

CONSTRUCTORS
  new
        my $heap = Data::Heap::Shared->new($path, $capacity);
        my $heap = Data::Heap::Shared->new($path, $capacity, $mode);
        my $heap = Data::Heap::Shared->new(undef, $capacity);

    Create or attach a heap. $capacity is the maximum number of elements. If
    $path is a defined filename, the heap is backed by that file (created if
    absent, attached if present). If $path is "undef", an anonymous mapping is
    used -- it has no backing file but is "MAP_SHARED", so it is inherited
    across "fork" and shared with child processes (an unrelated process simply
    cannot attach it).

    The optional $mode is an octal permission mask applied only when the
    backing file is created; it defaults to 0600 (owner-only). See "SECURITY".

    Croaks on error (bad capacity, permission denied, header mismatch, etc.).

  new_memfd
        my $heap = Data::Heap::Shared->new_memfd($name, $capacity);

    Create an anonymous heap backed by a Linux "memfd". $name is a label for
    debugging (as shown in "/proc"). The underlying file descriptor can be
    retrieved with "memfd" and passed to another process (e.g. over a unix
    socket or by inheritance) which attaches with "new_from_fd". Croaks on
    error.

  new_from_fd
        my $heap = Data::Heap::Shared->new_from_fd($fd);

    Attach to an existing heap given an open file descriptor for its backing
    store (typically obtained from "memfd" in another process). The header is
    validated on attach. Croaks on error. The descriptor you pass is
    duplicated ("F_DUPFD_CLOEXEC"), so it stays yours to close and closing it
    does not disturb the handle.

METHODS
  push
        my $ok = $heap->push($priority, $value);

    Insert a "($priority, $value)" integer pair. Returns true on success, or
    false if the heap is full (see "is_full"). Wakes one blocked "pop_wait"
    waiter.

  pop
        my ($pri, $val) = $heap->pop;

    Remove and return the lowest-priority element as a "($priority, $value)"
    pair. Returns the empty list if the heap is empty.

  pop_wait
        my ($pri, $val) = $heap->pop_wait;         # block forever
        my ($pri, $val) = $heap->pop_wait($secs);  # block up to $secs
        my ($pri, $val) = $heap->pop_wait(0);      # non-blocking

    Like "pop", but blocks (via futex) until an element is available. With no
    argument (or a negative timeout) it blocks indefinitely. A timeout of 0
    polls without blocking. A positive fractional $secs bounds the wait; on
    timeout the empty list is returned.

  peek
        my ($pri, $val) = $heap->peek;

    Return the lowest-priority element without removing it. Returns the empty
    list if the heap is empty.

  size
        my $n = $heap->size;

    Current number of elements.

  capacity
        my $cap = $heap->capacity;

    Maximum number of elements (fixed at creation).

  is_empty
        my $bool = $heap->is_empty;

    True if "size == 0".

  is_full
        my $bool = $heap->is_full;

    True if "size >= capacity".

  clear
        $heap->clear;

    Remove all elements (resets size to zero).

  path
        my $p = $heap->path;

    The backing file path, or "undef" for anonymous / memfd heaps.

  memfd
        my $fd = $heap->memfd;

    The backing file descriptor: the "memfd" of a "new_memfd" heap, or the
    dup'd fd of a "new_from_fd" heap. Such an fd can be shared with another
    process which attaches via "new_from_fd". Returns -1 for file-backed and