Promises::Channel - a coordination channel implemented with Promises
version 0.05
# 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.
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".
Note that decreasing the limit does not retroactively apply to items already queued, meaning that new callers "put" will block until the queue has been drained sufficiently.
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
.
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;
Creates a new merged channel from the supplied Promises::Channel instances. See Promises::Channel::Merged for a detailed explanation.
The following people have contributed to this module by supplying new features, bug reports, or feature requests.
- Erik Huelsmann (EHUELS)
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.