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 )