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 )