Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis/Channel.pod view on Meta::CPAN
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>
Buffer slot limit before C<put> parks (default: C<2_000_000_000>, effectively unbounded). Must be at least C<1>. If you
want backpressure, always set this explicitly.
=item * C<timeout =E<gt> $ms>
Default wait bound in milliseconds for any C<get> or C<put> that parks. If the wait exceeds this duration, it throws
L<Acme::Parataxis::Error::Timeout>. Default C<0> (no timeout).
=back
=head2 C<get( )>
my $val = $q->get;
Removes and returns the oldest value in the channel, parking the calling fiber if the channel is empty. Once a
shut-down channel has been fully drained, C<get> returns C<undef> forever. Honors the channel's configured C<timeout>.
=head2 C<put( $value )>
$q->put($msg);
Appends C<$value> to the tail, parking the calling fiber if the channel is full. If a deadline or token cuts the wait
short, the item is not queued. Honors the channel's configured C<timeout>.
=head2 C<try_get( )>
my ( $ok, $val ) = $q->try_get;
Non-blocking read. If an item is present, removes it and returns C<(1, $val)>. If empty, returns C<(0, undef)>
immediately without parking or arming timers.
=head2 C<try_put( $value )>
$q->try_put($msg) or warn "Buffer full, dropped";
Non-blocking write. If room is available, enqueues C<$value> and returns true. If full, returns false immediately
without parking.
=head2 C<put_priority( $value )>
$q->put_priority($urgent_msg);
Enqueues C<$value> immediately without ever parking, even if the channel is already at or above capacity. Used for
out-of-band control signals (such as an Actor's shutdown sentinel) and safe to call from destructors or contexts where
yielding is prohibited.
=head2 C<size( )>
Returns the number of unread items currently buffered.
=head2 C<capacity( )>
Returns the initial capacity configured during C<new>.
=head2 C<timeout( )>
Returns the configured default timeout in milliseconds (C<0> if none).
=head2 C<shutdown( )>
$q->shutdown;
Closes the channel to future writes. Wakes all fibers currently waiting in C<get()> or in a C<select> read case.
Buffered items remain accessible; once empty, all subsequent reads yield C<undef>. Idempotent.
=head2 C<adjust( $diff )>
lib/Acme/Parataxis/Channel.pod view on Meta::CPAN
while ( defined( my $item = $queue->get ) ) {
process_item($item);
}
say 'All items drained';
};
produce_into($queue);
$queue->shutdown;
Because EOF is signaled as C<undef>, avoid sending raw C<undef> values through the channel; wrap them in arrayrefs or
objects if undefined payloads are legitimate data.
=head2 Capacity-1 rendezvous
my $req_ch = Acme::Parataxis::Channel->new( capacity => 1 );
my $resp_ch = Acme::Parataxis::Channel->new( capacity => 1 );
fiber {
my $req = $req_ch->get;
$resp_ch->put( handle_request($req) );
};
$req_ch->put($payload);
my $reply = $resp_ch->get;
=head2 Multiplexing work and heartbeats
while (1) {
my ( $ch, $val ) = Acme::Parataxis::Channel->select(
[ $jobs, 'get' ],
[ $ticker, 'get' ],
timeout => 5000,
);
if ( !defined $ch ) {
warn "No activity for 5 seconds";
}
elsif ( $ch == $jobs ) {
last if !defined $val; # jobs channel was shut down
handle_job($val);
}
elsif ( $ch == $ticker ) {
send_heartbeat();
}
}
=head1 Behavior Notes
=over
=item * EOF semantics across methods
When a channel is shut down and drained, C<get> returns C<undef>, C<try_get> returns C<(1, undef)>, and a C<select> get
case returns C<($channel, undef)>. Check for defined values when reading from channels that may close.
=item * Backpressure is a park
When a bounded channel fills, producers park inside the scheduler rather than consuming system memory. This makes
cancellation safe: an interrupted C<put> simply aborts its registration, leaving the buffer untouched.
=item * Timeouts apply only to parking operations
A C<get> or C<put> that succeeds immediately never arms a timer. Neither C<try_get> nor C<try_put> ever consults the
configured timeout.
=back
=head1 SEE ALSO
L<Acme::Parataxis>, L<Acme::Parataxis::Stream>, L<Acme::Parataxis::Actor>, L<Acme::Parataxis::CancellationToken>
=head1 AUTHOR
Sanko Robinson L<https://github.com/sanko>
=head1 LICENSE
Copyright (C) Sanko Robinson.
This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License
2.
=cut
( run in 1.327 second using v1.01-cache-2.11-cpan-234fa220139 )