view release on metacpan or  search on metacpan

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

    my $ok = $cv->wait;            # unlock, wait for signal, re-lock
    my $ok = $cv->wait($timeout);  # with timeout
    $cv->signal;                   # wake one waiter
    $cv->broadcast;                # wake all waiters

    my $ok = $cv->wait_while(\&pred);           # loop until pred returns false
    my $ok = $cv->wait_while(\&pred, $timeout); # with timeout

C<wait> must be called while holding the mutex. Returns 1 on
signal/broadcast, 0 on timeout. The mutex is always re-acquired
before C<wait> returns.

C<wait_while> calls C<wait> in a loop until the predicate coderef
returns false. Returns 1 if predicate became false, 0 on timeout.

=head3 Guard

    my $g = $cv->lock_guard;       # unlock on scope exit

=head2 Data::Sync::Shared::Once

=head3 Constructors

    my $once = Data::Sync::Shared::Once->new($path);
    my $once = Data::Sync::Shared::Once->new(undef);
    my $once = Data::Sync::Shared::Once->new_memfd($name);
    my $once = Data::Sync::Shared::Once->new_from_fd($fd);

=head3 Operations

    my $init = $once->enter;             # try + wait, infinite
    my $init = $once->enter($timeout);   # with timeout
    $once->done;                         # mark initialization complete
    my $ok  = $once->is_done;            # check without blocking
    $once->reset;                        # reset to uninitialized state

C<enter> returns true for exactly one process (the initializer).
All others block until C<done> is called, then return false.
If the initializer dies, stale PID detection elects a new one.

=head2 Common Methods

All primitives support:

    my $p  = $obj->path;           # backing file path (undef if anon)
    my $fd = $obj->memfd;          # memfd fd (-1 if file-backed/anon)
    $obj->sync;                    # msync — flush to disk
    $obj->unlink;                  # remove backing file
    Class->unlink($path);          # class method form
    my $s  = $obj->stats;          # diagnostic hashref

Stats keys vary by type. All counters are approximate under concurrency.

B<Semaphore:> C<value>, C<max>, C<waiters>, C<mmap_size>, C<acquires>,
C<releases>, C<waits>, C<timeouts>, C<recoveries>.

B<Barrier:> C<parties>, C<arrived>, C<generation>, C<waiters>,
C<mmap_size>, C<waits>, C<releases>, C<timeouts>.

B<RWLock:> C<state> (C<"unlocked">, C<"read_locked">, C<"write_locked">),
C<readers>, C<waiters>, C<mmap_size>, C<acquires>, C<releases>,
C<recoveries>.

B<Condvar:> C<waiters>, C<signals>, C<mmap_size>, C<acquires>,
C<releases>, C<waits>, C<timeouts>, C<recoveries>.

B<Once:> C<state> (C<"init">, C<"running">, C<"done">), C<is_done>,
C<waiters>, C<mmap_size>, C<acquires>, C<releases>, C<waits>,
C<timeouts>, C<recoveries>.

=head3 eventfd Integration

    my $fd = $obj->eventfd;        # create eventfd, returns fd
    $obj->eventfd_set($fd);        # use existing fd (e.g. from fork)
    my $fd = $obj->fileno;         # current eventfd (-1 if none)
    $obj->notify;                  # signal eventfd
    my $n  = $obj->eventfd_consume;  # drain notification counter

Notification is opt-in. Use with L<EV> or other event loops.

=head1 SEE ALSO

L<Data::Buffer::Shared> - typed shared array

L<Data::HashMap::Shared> - concurrent hash table

L<Data::Queue::Shared> - FIFO queue

L<Data::PubSub::Shared> - publish-subscribe ring

L<Data::ReqRep::Shared> - request-reply

L<Data::Pool::Shared> - fixed-size object pool

L<Data::Stack::Shared> - LIFO stack

L<Data::Deque::Shared> - double-ended queue

L<Data::Log::Shared> - append-only log (WAL)

L<Data::Heap::Shared> - priority queue

L<Data::Graph::Shared> - directed weighted graph

L<Data::BitSet::Shared> - shared bitset (lock-free per-bit ops)

L<Data::RingBuffer::Shared> - fixed-size overwriting ring buffer

=head1 AUTHOR

vividsnow

=head1 LICENSE

This is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

=cut