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.