view release on metacpan or  search on metacpan

local/lib/perl5/IO/Async/Channel.pm  view on Meta::CPAN

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2011-2015 -- leonerd@leonerd.org.uk

package IO::Async::Channel;

use strict;
use warnings;
use base qw( IO::Async::Notifier );

our $VERSION = '0.70';

use Carp;

use IO::Async::Stream;

=head1 NAME

C<IO::Async::Channel> - pass values into or out from an L<IO::Async::Routine>

=head1 DESCRIPTION

A C<IO::Async::Channel> object allows Perl values to be passed into or out of
an L<IO::Async::Routine>. It is intended to be used primarily with a Routine
object rather than independently. For more detail and examples on how to use
this object see also the documentation for L<IO::Async::Routine>.

A Channel object is shared between the main process of the program and the
process running within the Routine. In the main process it will be used in
asynchronous mode, and in the Routine process it will be used in synchronous
mode. In asynchronous mode all methods return immediately and use
L<IO::Async>-style futures or callback functions. In synchronous within the
Routine process the methods block until they are ready and may be used for
flow-control within the routine. Alternatively, a Channel may be shared
between two different Routine objects, and not used directly by the
controlling program.

The channel itself represents a FIFO of Perl reference values. New values may
be put into the channel by the C<send> method in either mode. Values may be
retrieved from it by the C<recv> method. Values inserted into the Channel are
snapshot by the C<send> method. Any changes to referred variables will not be
observed by the other end of the Channel after the C<send> method returns.

=head1 PARAMETERS

The following named parameters may be passed to C<new> or C<configure>:

=head2 codec => STR

Gives the name of the encoding method used to represent values over the
channel.

This can be set to C<Storable> to use the core L<Storable> module. As this
only supports references, to pass a single scalar value, C<send> a SCALAR
reference to it, and dereference the result of C<recv>.

If the L<Sereal::Encoder> and L<Sereal::Decoder> modules are installed, this
can be set to C<Sereal> instead, and will use those to perform the encoding
and decoding. This optional dependency may give higher performance than using
C<Storable>.

Currently, the default choice is always C<Storable>. However, a later version
may switch to using C<Sereal> if the appropriate modules are available. Most
users of this module should not need to worry about the default. It may matter
if the C<send_frozen> method is being used to send pre-encoded data. Code that
tries to do this should be changed to use the C<encode> method and
C<send_encoded> instead.

=cut

=head1 CONSTRUCTOR

=cut

=head2 new

   $channel = IO::Async::Channel->new

Returns a new C<IO::Async::Channel> object. This object reference itself
should be shared by both sides of a C<fork()>ed process. After C<fork()> the
two C<setup_*> methods may be used to configure the object for operation on
either end.

While this object does in fact inherit from L<IO::Async::Notifier>, it should
not be added to a Loop object directly; event management will be handled by
its containing L<IO::Async::Routine> object.

=cut

=head1 METHODS

The following methods documented with a trailing call to C<< ->get >> return