Acme-Parataxis

 view release on metacpan or  search on metacpan

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

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis::Sync::Mutex - Non-Reentrant Mutual Exclusion Lock with True Owner Tracking

=head1 SYNOPSIS

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

    my $lock  = Acme::Parataxis::Sync::Mutex->new;
    my $count = 0;

    async {
        my @workers = map {
            fiber {
                my $guard = $lock->guard;    # acquired; released on scope exit
                $count++;
            };
        } 1 .. 10;

        $_->await for @workers;
        say "Final count: $count";           # 10
    };

=head1 DESCRIPTION

C<Acme::Parataxis::Sync::Mutex> is a cooperative mutual exclusion lock designed for fibers. It tracks the identity of
the holding fiber explicitly: only the fiber that acquired the lock may release it.

Key guarantees:

=over

=item *

B<Non-reentrant>: Attempting to lock a mutex you already hold croaks with C<Mutex is not reentrant: this fiber already
holds the lock>. This makes self-deadlocks loud, immediate failures rather than silent hangs.

=item *

B<Fair, FIFO hand-off>: When a fiber unlocks the mutex, the lock is handed directly to the longest-waiting fiber in the
queue. The ownership transition is atomic: C<owner> is assigned to the waking fiber B<before> it is re-enqueued onto
the scheduler run queue, preventing unqueued fibers from barging in and stealing the lock.

=item *

B<Cancellable waits>: Waiting fibers park cooperatively and can be interrupted by C<with_timeout> or cancellation
tokens. An interrupted waiter removes itself from the queue cleanly.

=back

=head1 METHODS

=head2 C<new( )>

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

Constructs a new, unlocked mutex. Takes no arguments.



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