Acme-Parataxis

 view release on metacpan or  search on metacpan

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

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis::Sync - Base Class for Fiber Synchronization Primitives

=head1 SYNOPSIS

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

    my $lock  = Acme::Parataxis::Sync::Mutex->new;
    my $group = Acme::Parataxis::Sync::WaitGroup->new;

    async {
        $group->add(4);

        for my $id ( 1 .. 4 ) {
            fiber {
                my $guard = $lock->guard;    # mutex held for scope of $guard
                perform_exclusive_operation($id);
                $group->done;
            };
        }

        $group->wait;    # parks until all 4 workers call done()
        say 'All workers completed safely!';
    };

=head1 DESCRIPTION

C<Acme::Parataxis::Sync> is the abstract base class powering the Parataxis synchronization primitive family:

=over

=item * L<Acme::Parataxis::Sync::Mutex> - Non-reentrant mutual exclusion locks with owner tracking and scope guards.

=item * L<Acme::Parataxis::Sync::RwLock> - Writer-preferring reader/writer locks with shared and exclusive guards.

=item * L<Acme::Parataxis::Sync::WaitGroup> - Concurrency counters that block until tasks decrement to zero.

=item * L<Acme::Parataxis::Sync::Barrier> - Fixed-party phase rendezvous gates.

=item * L<Acme::Parataxis::Sync::Once> - Thread-safe, single-execution initializers.

=back

All primitives share uniform operational guarantees:

=over

=item *

B<Scheduled cooperative parking>: Waiting fibers suspend cleanly in the scheduler; neither the OS thread nor the event
loop is ever blocked.

=item *

B<Context validation>: Methods that manage locks or waits resolve the calling fiber's ID immediately via C<_fid()>,



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