view release on metacpan or  search on metacpan

lib/Data/Heap/Shared.pm  view on Meta::CPAN

mutex recovery. Futex blocking when empty.

B<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 C<clear> and rebuild if crash recovery
is triggered in a critical application.

B<Linux-only>. Requires 64-bit Perl.

=head1 CONSTRUCTORS

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

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

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

=head2 new_memfd

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

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

=head2 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 L</memfd> in another process).
The header is validated on attach. Croaks on error. The descriptor you
pass is duplicated (C<F_DUPFD_CLOEXEC>), so it stays yours to close and
closing it does not disturb the handle.

=head1 METHODS

=head2 push

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

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

=head2 pop

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

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

=head2 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 L</pop>, but blocks (via futex) until an element is available.
With no argument (or a negative timeout) it blocks indefinitely. A
timeout of C<0> polls without blocking. A positive fractional
C<$secs> bounds the wait; on timeout the empty list is returned.

=head2 peek

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

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

=head2 size

    my $n = $heap->size;

Current number of elements.

=head2 capacity

    my $cap = $heap->capacity;

Maximum number of elements (fixed at creation).

=head2 is_empty

    my $bool = $heap->is_empty;

True if C<< size == 0 >>.

=head2 is_full

    my $bool = $heap->is_full;

True if C<< size >= capacity >>.

=head2 clear

    $heap->clear;

Remove all elements (resets size to zero).

=head2 path

    my $p = $heap->path;