Acme-Parataxis

 view release on metacpan or  search on metacpan

lib/Acme/Parataxis/Sync/Barrier.pod  view on Meta::CPAN

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis::Sync::Barrier - Phase-Boundary Rendezvous Synchronization for Fibers

=head1 SYNOPSIS

    use v5.40;
    use Acme::Parataxis qw[async fiber];
    use Acme::Parataxis::Sync::Barrier;

    my $barrier = Acme::Parataxis::Sync::Barrier->new( parties => 3 );
    my @log;

    async {
        my @workers = map {
            my $id = $_;
            fiber {
                for my $phase ( 1 .. 2 ) {
                    $barrier->arrive_and_wait;    # blocks until all 3 fibers arrive
                    push @log, "worker_$id/phase_$phase";
                }
            };
        } 1 .. 3;

        $_->await for @workers;
        say "Crossed: " . join(' ', @log);
    };

=head1 DESCRIPTION

An C<Acme::Parataxis::Sync::Barrier> provides a synchronized rendezvous point for a fixed number of fibers. Fibers
arrive at the barrier by calling C<arrive_and_wait()>. The first C<parties - 1> fibers park; the final arrival
immediately unblocks all waiting fibers simultaneously and re-arms the barrier for the next phase.

Barriers are ideal for lockstep algorithms, phased pipelines, and parallel computations where intermediate data from a
given stage must be completely produced before any worker is permitted to begin the next stage.

=over

=item *

B<Cyclic re-arming>: A barrier automatically resets its arrival counter to C<parties> as soon as a phase is released,
allowing a single barrier instance to coordinate multiple consecutive rounds.

=item *

B<Zero-wait final arrival>: The fiber that registers the final arrival does not park; it enqueues the waiting fibers
and returns immediately.

=back

=head1 METHODS

=head2 C<new( parties =E<gt> $n )>

    my $barrier = Acme::Parataxis::Sync::Barrier->new( parties => 4 );

Constructs a barrier requiring C<$n> arrivals per phase. C<parties> is required and must be an integer C<E<gt>= 1>.
Croaks if C<parties> is less than 1.



( run in 1.192 second using v1.01-cache-2.11-cpan-234fa220139 )