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 )