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 )