Promises::Channel - a coordination channel implemented with Promises
version 0.03
# See notes about recursion in Promises::Cookbook::Recursion use Promises backend => ['AE'], 'deferred'; use Promises::Channel qw(channel); my $channel = channel limit => 4; # Use $channel to invert control on an AnyEvent::Handle $ae_handle->on_read(sub { my $handle = shift; $handle->push_read(line => sub { my ($handle, $line) = @_; $channel->put($line); }); }); $ae_handle->on_error(sub { $channel->shutdown; }); my $depleted = 0; $channel->on_shutdown ->then(sub { $depleted = 1 }); sub reader { my ($channel, $line) = @_; do_stuff $line; # Queue the next read, using done to avoid recursion $channel->get->done(\&reader); } $channel->get->then(\&reader);
A Promises::Channel is a FIFO queue that produces Promises::Promises which resolve to the items added to the queue.
Promises::Channel
Sets an upper boundary on the number of items which may be queued at a time. If this limit is reached, the promise returned by the next call to "put" will not be resolved until there has been a corresponding call to "get" (or the channel has been "shutdown".
Returns true if the channel has been shutdown. The channel will be automatically shutdown and drained when demolished.
Returns the number of items in the queue. This number is not adjusted to reflect any queued waiters.
If a "limit" has been set, returns true if the channel is full and cannot immediately accept new items.
Returns true if there are no items in the queue and there are no pending deliveries of items from deferred "put"s.
Adds one or more items to the channel and returns a Promises::Promise that will resolve to the channel instance after the item has been added (which may be deferred if "limit" has been set).
Returns a Promises::Promise which will resolve to the channel and the next item queued in the channel.
$chan->get->then(sub { my ($chan, $item) = @_; ... });
Closes the queue. This does not prevent new items from being added. However, future calls to "get" will be resolved immediately with undef. Any previously deferred calls to get will be immediately resolved until the channel is empty, after which any remaining deferrals will be resolved with undef.
undef
When the channel goes out of scope, it will be shutdown and drained automatically.
Returns a promise which will be resolved after the channel has been shut down and drained. As the channel is shut down when demolished, this promise will be resolved when the channel goes out of scope as well.
Nothing is exported by default.
Sugar for calling the default constructor. The following lines are equivalent.
my $ch = chan; my $ch = channel; my $ch = Promises::Channel->new;
The following people have contributed to this module by supplying new features, bug reports, or feature requests.
Jeff Ober <sysread@fastmail.fm>
This software is copyright (c) 2019 by Jeff Ober.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Promises::Channel, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Promises::Channel
CPAN shell
perl -MCPAN -e shell install Promises::Channel
For more information on module installation, please visit the detailed CPAN module installation guide.