Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis/Signal.pod view on Meta::CPAN
=pod
=encoding utf8
=head1 NAME
Acme::Parataxis::Signal - One-Shot Event Flags with Waiter Queues
=head1 SYNOPSIS
use v5.40;
use Acme::Parataxis qw[async fiber];
use Acme::Parataxis::Signal;
# Initialize unsignalled (count => false):
my $ready = Acme::Parataxis::Signal->new( count => false );
async {
fiber {
say 'Worker: waiting for ready signal...';
$ready->wait; # parks until signalled
say 'Worker: unblocked and running!';
};
say 'Main: completing setup...';
$ready->send; # wakes the worker fiber
};
=head1 DESCRIPTION
An C<Acme::Parataxis::Signal> represents a single notification flag accompanied by a FIFO queue of waiters. Calling
C<send> signals the event, waking a parked fiber or saving the notification for the next fiber that arrives.
A key design feature of signals is B<early firing safety>: if C<send> is called before any fiber has called C<wait>,
the signal is remembered. When a fiber eventually calls C<wait>, it consumes the remembered signal and proceeds
immediately without parking. This eliminates initialization race conditions where a notifier fires before its listeners
are spawned.
=over
=item *
C<send()> releases B<one> waiter, or records the signal if no waiters exist.
=item *
C<broadcast()> wakes B<all> currently queued waiters simultaneously, clearing any remembered signal.
=back
=head1 METHODS
=head2 C<new( [ count =E<gt> $bool = true ] )>
my $ready = Acme::Parataxis::Signal->new( count => false ); # unsignalled (common case)
my $fired = Acme::Parataxis::Signal->new; # pre-signalled
Constructs a new signal.
B<Important Default>: C<count> defaults to B<true> (pre-signalled). In this state, the first C<wait()> will not block.
For the standard pattern where waiters must park until an event occurs, pass C<< count => false >>.
=head2 C<send( )>
( run in 0.334 second using v1.01-cache-2.11-cpan-234fa220139 )