/ 
Acme-Parataxis-v0.1.3
/ Acme::Parataxis::Sync::Barrier

NAME

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

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);
};

DESCRIPTION

An Acme::Parataxis::Sync::Barrier provides a synchronized rendezvous point for a fixed number of fibers. Fibers arrive at the barrier by calling arrive_and_wait(). The first 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.

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

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

METHODS

new( parties => $n )

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

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

arrive_and_wait( )

$barrier->arrive_and_wait;

Registers the current fiber's arrival in the current phase.

  • If fewer than parties have arrived, the calling fiber parks until the remaining parties arrive.

  • If this call represents the final arrival (remaining == 1), it bumps the generation counter, resets remaining to parties, wakes all parked parties, and returns true immediately without yielding.

Must be called from within a scheduled fiber (croaks otherwise).

parties( )

Returns the total number of participating fibers required to open a phase.

remaining( )

Returns the number of arrivals still required to complete the current phase.

waiters( )

Returns the number of fibers currently parked waiting for the phase to complete.

Recipes

Multiphase lockstep iteration

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

async {
    my $f1 = fiber {
        for my $round ( 1 .. 3 ) {
            compute_part_a($round);
            $barrier->arrive_and_wait;
        }
    };

    my $f2 = fiber {
        for my $round ( 1 .. 3 ) {
            compute_part_b($round);
            $barrier->arrive_and_wait;
        }
    };

    $f1->await;
    $f2->await;
};

Behavior Notes

  • Interrupted arrivals consume quota

    When a fiber calls arrive_and_wait(), remaining is decremented immediately. If that fiber's wait is interrupted by a timeout or cancellation token, the fiber unregisters from the queue, but the slot it claimed is not refunded. The barrier remains one arrival short until a replacement arrival occurs.

  • Deadlock risk if workers fail to arrive

    A barrier never opens on its own; it requires exactly parties arrivals. If a participant dies before arriving, surviving waiters will park permanently, triggering a scheduler deadlock error unless protected by with_timeout.

SEE ALSO

Acme::Parataxis::Sync, Acme::Parataxis::Sync::WaitGroup, Acme::Parataxis::Sync::Mutex

AUTHOR

Sanko Robinson https://github.com/sanko

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2.