view release on metacpan or  search on metacpan

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

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis::Semaphore - A counting semaphore for fiber synchronization

=head1 SYNOPSIS

    use Acme::Parataxis;
    use Acme::Parataxis::Semaphore;

    my $sem = Acme::Parataxis::Semaphore->new;   # unlocked by default

    async {
        fiber { $sem->down };   # wait for a signal
        $sem->up;
    };

=head1 DESCRIPTION

A simple integer counter that optionally blocks fibers when it reaches zero. There is no owner associated with a
semaphore, so one fiber can C<down> it while another can C<up> it, C<up> may be called before C<down>, and so on.

Blocked fibers are parked (they do not busy-wait) and are resumed in FIFO order as permits become available, exactly
like the futures used by C<await>.

=head1 CONSTRUCTOR

=head2 C<new( [...] )>

    my $sem = Acme::Parataxis::Semaphore->new;
    my $sem = Acme::Parataxis::Semaphore->new(count => 3);

Creates a new semaphore. The optional C<count> parameter sets the initial number of permits and defaults to C<1>.

=head1 METHODS

=head2 C<down( )>

    $sem->down;

Acquire a permit. If the count is zero, the current fiber is suspended until a permit becomes available. Decrements the
count upon success.

=head2 C<up( )>

    $sem->up;

Release a permit. Increments the count and wakes one blocked waiter if any are queued.

=head2 C<try( )>

    my $acquired = $sem->try;

Attempt to acquire a permit without blocking. Returns true and decrements the count if a permit is available; returns
false immediately otherwise. This is useful when you want to opportunistically grab a permit but don't want to stall
the fiber.

=head2 C<adjust( $diff )>

    $sem->adjust($diff);