Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sysread/promises-channel

A coordination channel implemented with Promises
https://github.com/sysread/promises-channel

channel perl promise promises

Last synced: about 1 month ago
JSON representation

A coordination channel implemented with Promises

Awesome Lists containing this project

README 

        
=pod



=encoding UTF-8



=head1 NAME



Promises::Channel - a coordination channel implemented with Promises



=head1 VERSION



version 0.05



=head1 SYNOPSIS



  # 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);



=head1 DESCRIPTION



A C is a FIFO queue that produces Ls

which resolve to the items added to the queue.



=head1 ATTRIBUTES



=head2 limit



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 L will

not be resolved until there has been a corresponding call to L (or the

channel has been L.



Note that decreasing the limit does not retroactively apply to items already

queued, meaning that new callers L will block until the queue has been

drained sufficiently.



=head2 is_shutdown



Returns true if the channel has been shutdown. The channel will be

automatically shutdown and drained when demolished.



=head1 METHODS



=head2 size



Returns the number of items in the queue. This number is not adjusted to

reflect any queued waiters.



=head2 is_full



If a L has been set, returns true if the channel is full and cannot

immediately accept new items.



=head2 is_empty



Returns true if there are no items in the queue and there are no pending

deliveries of items from deferred Ls.



=head2 put



Adds one or more items to the channel and returns a L that

will resolve to the channel instance after the item has been added (which may

be deferred if L has been set).



=head2 get



Returns a L which will resolve to the channel and the next

item queued in the channel.



  $chan->get->then(sub {

    my ($chan, $item) = @_;

    ...

  });



=head2 shutdown



Closes the queue. This does not prevent new items from being added. However,

future calls to L will be resolved immediately with C. Any

previously deferred calls to get will be immediately resolved until the channel

is empty, after which any remaining deferrals will be resolved with C.



When the channel goes out of scope, it will be shutdown and drained

automatically.



=head2 on_shutdown



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.



=head1 EXPORTS



Nothing is exported by default.



=head2 chan



=head2 channel



Sugar for calling the default constructor. The following lines are equivalent.



  my $ch = chan;

  my $ch = channel;

  my $ch = Promises::Channel->new;



=head2 merge



Creates a new merged channel from the supplied L instances.

See L for a detailed explanation.



=head1 CONTRIBUTORS



The following people have contributed to this module by supplying new features,

bug reports, or feature requests.



=over



=item Erik Huelsmann (EHUELS)



=back



=head1 AUTHOR



Jeff Ober 



=head1 COPYRIGHT AND LICENSE



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.



=cut