view release on metacpan or  search on metacpan

local/lib/perl5/IO/Async/Socket.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::Socket;

use strict;
use warnings;

our $VERSION = '0.70';

use base qw( IO::Async::Handle );

use Errno qw( EAGAIN EWOULDBLOCK EINTR );

use Carp;

=head1 NAME

C<IO::Async::Socket> - event callbacks and send buffering for a socket
filehandle

=head1 SYNOPSIS

 use IO::Async::Socket;

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

 my $socket = IO::Async::Socket->new(
    on_recv => sub {
       my ( $self, $dgram, $addr ) = @_;

       print "Received reply: $dgram\n",
       $loop->stop;
    },
    on_recv_error => sub {
       my ( $self, $errno ) = @_;
       die "Cannot recv - $errno\n";
    },
 );
 $loop->add( $socket );

 $socket->connect(
    host     => "some.host.here",
    service  => "echo",
    socktype => 'dgram',
 )->get;

 $socket->send( "A TEST DATAGRAM" );

 $loop->run;

=head1 DESCRIPTION

This subclass of L<IO::Async::Handle> contains a socket filehandle. It
provides a queue of outgoing data. It invokes the C<on_recv> handler when new
data is received from the filehandle. Data may be sent to the filehandle by
calling the C<send> method.

It is primarily intended for C<SOCK_DGRAM> or C<SOCK_RAW> sockets (such as UDP
or packet-capture); for C<SOCK_STREAM> sockets (such as TCP) an instance of
L<IO::Async::Stream> is more appropriate.

=head1 EVENTS

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

=head2 on_recv $data, $addr

Invoke on receipt of a packet, datagram, or stream segment.

The C<on_recv> handler is invoked once for each packet, datagram, or stream
segment that is received. It is passed the data itself, and the sender's
address.

=head2 on_recv_error $errno

Optional. Invoked when the C<recv> method on the receiving handle fails.

=head2 on_send_error $errno

Optional. Invoked when the C<send> method on the sending handle fails.

The C<on_recv_error> and C<on_send_error> handlers are passed the value of
C<$!> at the time the error occured. (The C<$!> variable itself, by its
nature, may have changed from the original error by the time this handler
runs so it should always use the value passed in).

If an error occurs when the corresponding error callback is not supplied, and
there is not a subclass method for it, then the C<close> method is
called instead.

=head2 on_outgoing_empty

Optional. Invoked when the sending data buffer becomes empty.

=cut

sub _init
{
   my $self = shift;

   $self->{recv_len} = 65536;

   $self->SUPER::_init( @_ );
}

=head1 PARAMETERS