Acme-Parataxis

 view release on metacpan or  search on metacpan

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

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis::Channel - Bounded Message Queues and CSP Multiplexing for Fibers

=head1 SYNOPSIS

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

    my $log = Acme::Parataxis::Channel->new( capacity => 1024 );

    async {
        # Producer: parks while the channel is full
        fiber {
            $log->put($_) for 1 .. 8;
            $log->shutdown;
        };

        # Consumer: parks while the channel is empty; stops on EOF (undef)
        while ( defined( my $msg = $log->get ) ) {
            say "Received: $msg";
        }
    };

=head1 DESCRIPTION

A channel is a buffer with two ends and a capacity. C<put> appends to the tail, C<get> removes from the head, and both
ends can be shared across any number of concurrent fibers.

Capacity drives backpressure: when the buffer is full, producers park; when it is empty, consumers park. A slow reader
naturally pushes back on a fast writer, preventing unbounded queue growth in memory. Setting C<capacity =E<gt> 1>
creates a rendezvous channel: a C<put> will only complete once a C<get> is actively waiting to take the value.

Every park here is a standard fiber wait. L<with_timeout|Acme::Parataxis/with_timeout> and
L<Acme::Parataxis::CancellationToken> interrupt a C<get> or C<put> cleanly: an interrupted C<put> leaves nothing in the
channel, and an interrupted C<get> leaves the next queued item for subsequent readers.

Calling C<shutdown> closes the write side. Any items already buffered remain available to C<get>. Once drained,
subsequent C<get> calls return C<undef> immediately without parking. This is the canonical way to signal EOF down a
pipeline and allows L<Acme::Parataxis::Stream> stages to unwind cleanly.

Channels serve as the internal substrate across Parataxis: an L<Actor|Acme::Parataxis::Actor> mailbox is a channel, a
L<Ticker|Acme::Parataxis::Ticker> publishes ticks through a capacity-1 channel, and a
L<Supervisor|Acme::Parataxis::Supervisor> aggregates worker crashes through one.

=head1 METHODS

=head2 C<new( [%opts] )>

    my $q = Acme::Parataxis::Channel->new;                           # effectively unbounded
    my $q = Acme::Parataxis::Channel->new( capacity => 1024 );       # bounded: put parks when full
    my $q = Acme::Parataxis::Channel->new( capacity => 8, timeout => 200 );

Named arguments only:

=over

=item * C<capacity =E<gt> $int>



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