view release on metacpan or  search on metacpan

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

 use IO::Async::Loop;
 my $loop = IO::Async::Loop->new;

 my $socket = IO::Socket::INET->new( LocalPort => 1234, Listen => 1 );

 my $handle = IO::Async::Handle->new(
    handle => $socket,

    on_read_ready  => sub {
       my $new_client = $socket->accept; 
       ...
    },
 );

 $loop->add( $handle );

For most other uses with sockets, pipes or other filehandles that carry a byte
stream, the L<IO::Async::Stream> class is likely to be more suitable. For
non-stream sockets, see L<IO::Async::Socket>.

=head1 DESCRIPTION

This subclass of L<IO::Async::Notifier> allows non-blocking IO on filehandles.
It provides event handlers for when the filehandle is read- or write-ready.

=cut

=head1 EVENTS

The following events are invoked, either using subclass methods or CODE
references in parameters:

=head2 on_read_ready

Invoked when the read handle becomes ready for reading.

=head2 on_write_ready

Invoked when the write handle becomes ready for writing.

=head2 on_closed

Optional. Invoked when the handle becomes closed.

This handler is invoked before the filehandles are closed and the Handle
removed from its containing Loop. The C<loop> will still return the containing
Loop object.

=cut

=head1 PARAMETERS

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

=head2 read_handle => IO

=head2 write_handle => IO

The reading and writing IO handles. Each must implement the C<fileno> method.
Primarily used for passing C<STDIN> / C<STDOUT>; see the SYNOPSIS section of
L<IO::Async::Stream> for an example.

=head2 handle => IO

The IO handle for both reading and writing; instead of passing each separately
as above. Must implement C<fileno> method in way that C<IO::Handle> does.

=head2 read_fileno => INT

=head2 write_fileno => INT

File descriptor numbers for reading and writing. If these are given as an
alternative to C<read_handle> or C<write_handle> then a new C<IO::Handle>
instance will be constructed around each.

=head2 on_read_ready => CODE

=head2 on_write_ready => CODE

=head2 on_closed => CODE

CODE references for event handlers.

=head2 want_readready => BOOL

=head2 want_writeready => BOOL

If present, enable or disable read- or write-ready notification as per the
C<want_readready> and C<want_writeready> methods.

It is required that a matching C<on_read_ready> or C<on_write_ready> are
available for any handle that is provided; either passed as a callback CODE
reference or as an overridden the method. I.e. if only a C<read_handle> is
given, then C<on_write_ready> can be absent. If C<handle> is used as a
shortcut, then both read and write-ready callbacks or methods are required.

If no IO handles are provided at construction time, the object is still
created but will not yet be fully-functional as a Handle. IO handles can be
assigned later using the C<set_handle> or C<set_handles> methods, or by
C<configure>. This may be useful when constructing an object to represent a
network connection, before the C<connect(2)> has actually been performed yet.

=cut

sub configure
{
   my $self = shift;
   my %params = @_;

   if( exists $params{on_read_ready} ) {
      $self->{on_read_ready} = delete $params{on_read_ready};
      undef $self->{cb_r};

      $self->_watch_read(0), $self->_watch_read(1) if $self->want_readready;
   }

   if( exists $params{on_write_ready} ) {
      $self->{on_write_ready} = delete $params{on_write_ready};
      undef $self->{cb_w};