.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IO::Async::Listener 3pm"
.TH IO::Async::Listener 3pm "2012-10-24" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"IO::Async::Listener" \- listen on network sockets for incoming connections
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use IO::Async::Listener;
\&
\& use IO::Async::Loop;
\& my $loop = IO::Async::Loop\->new;
\&
\& my $listener = IO::Async::Listener\->new(
\&    on_stream => sub {
\&       my ( undef, $stream ) = @_;
\&
\&       $stream\->configure(
\&          on_read => sub {
\&             my ( $self, $buffref, $eof ) = @_;
\&             $self\->write( $$buffref );
\&             $$buffref = "";
\&             return 0;
\&          },
\&       );
\&       
\&       $loop\->add( $stream );
\&    },
\& );
\&
\& $loop\->add( $listener );
\&
\& $listener\->listen(
\&    service  => "echo",
\&    socktype => \*(Aqstream\*(Aq,
\&
\&    on_resolve_error => sub { print STDERR "Cannot resolve \- $_[0]\en"; },
\&    on_listen_error  => sub { print STDERR "Cannot listen\en"; },
\& );
\&
\& $loop\->run;
.Ve
.PP
This object can also be used indirectly via an \f(CW\*(C`IO::Async::Loop\*(C'\fR:
.PP
.Vb 1
\& use IO::Async::Stream;
\&
\& use IO::Async::Loop;
\& my $loop = IO::Async::Loop\->new;
\&
\& $loop\->listen(
\&    service  => "echo",
\&    socktype => \*(Aqstream\*(Aq,
\&
\&    on_stream => sub {
\&       ...
\&    },
\&
\&    on_resolve_error => sub { print STDERR "Cannot resolve \- $_[0]\en"; },
\&    on_listen_error  => sub { print STDERR "Cannot listen\en"; },
\& );
\&
\& $loop\->run;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This subclass of IO::Async::Handle adds behaviour which watches a socket in
listening mode, to accept incoming connections on them.
.PP
A Listener can be constructed and given a existing socket in listening mode.
Alternatively, the Listener can construct a socket by calling the \f(CW\*(C`listen\*(C'\fR
method. Either a list of addresses can be provided, or a service name can be
looked up using the underlying loop's \f(CW\*(C`resolve\*(C'\fR method.
.SH "EVENTS"
.IX Header "EVENTS"
The following events are invoked, either using subclass methods or \s-1CODE\s0
references in parameters:
.ie n .SS "on_accept $clientsocket"
.el .SS "on_accept \f(CW$clientsocket\fP"
.IX Subsection "on_accept $clientsocket"
Invoked whenever a new client connects to the socket.
.ie n .SS "on_stream $stream"
.el .SS "on_stream \f(CW$stream\fP"
.IX Subsection "on_stream $stream"
An alternative to \f(CW\*(C`on_accept\*(C'\fR, this an instance of IO::Async::Stream when
a new client connects. This is provided as a convenience for the common case
that a Stream object is required as the transport for a Protocol object.
.ie n .SS "on_socket $socket"
.el .SS "on_socket \f(CW$socket\fP"
.IX Subsection "on_socket $socket"
Similar to \f(CW\*(C`on_stream\*(C'\fR, but constructs an instance of IO::Async::Socket.
This is most useful for \f(CW\*(C`SOCK_DGRAM\*(C'\fR or \f(CW\*(C`SOCK_RAW\*(C'\fR sockets.
.ie n .SS "on_accept_error $socket, $errno"
.el .SS "on_accept_error \f(CW$socket\fP, \f(CW$errno\fP"
.IX Subsection "on_accept_error $socket, $errno"
Optional. Invoked if the \f(CW\*(C`accept\*(C'\fR syscall indicates an error (other than
\&\f(CW\*(C`EAGAIN\*(C'\fR or \f(CW\*(C`EWOULDBLOCK\*(C'\fR). If not provided, failures of \f(CW\*(C`accept\*(C'\fR will
simply be ignored.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
The following named parameters may be passed to \f(CW\*(C`new\*(C'\fR or \f(CW\*(C`configure\*(C'\fR:
.IP "on_accept => \s-1CODE\s0" 8
.IX Item "on_accept => CODE"
.PD 0
.IP "on_stream => \s-1CODE\s0" 8
.IX Item "on_stream => CODE"
.IP "on_socket => \s-1CODE\s0" 8
.IX Item "on_socket => CODE"
.PD
\&\s-1CODE\s0 reference for the event handlers. Because of the mutually-exclusive
nature of their behaviour, only one of these may be set at a time. Setting one
will remove the other two.
.IP "handle => \s-1IO\s0" 8
.IX Item "handle => IO"
The \s-1IO\s0 handle containing an existing listen-mode socket.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$name = $listener\->sockname"
.el .SS "\f(CW$name\fP = \f(CW$listener\fP\->sockname"
.IX Subsection "$name = $listener->sockname"
Returns the \f(CW\*(C`sockname\*(C'\fR of the underlying listening socket
.ie n .SS "$family = $listener\->family"
.el .SS "\f(CW$family\fP = \f(CW$listener\fP\->family"
.IX Subsection "$family = $listener->family"
Returns the socket address family of the underlying listening socket
.ie n .SS "$socktype = $listener\->socktype"
.el .SS "\f(CW$socktype\fP = \f(CW$listener\fP\->socktype"
.IX Subsection "$socktype = $listener->socktype"
Returns the socket type of the underlying listening socket
.ie n .SS "$listener\->listen( %params )"
.el .SS "\f(CW$listener\fP\->listen( \f(CW%params\fP )"
.IX Subsection "$listener->listen( %params )"
This method sets up a listening socket using the addresses given, and will
invoke the \f(CW\*(C`on_accept\*(C'\fR callback each time a new connection is accepted on the
socket. Addresses may be given directly, or they may be looked up using the
system's name resolver.
.PP
If multiple addresses are given, or resolved from the service and hostname,
then each will be attempted in turn until one succeeds.
.PP
In plain address mode, the \f(CW%params\fR hash takes the following keys:
.IP "addrs => \s-1ARRAY\s0" 8
.IX Item "addrs => ARRAY"
Reference to an array of (possibly-multiple) address structures to attempt to
listen on. Each should be in the layout described for \f(CW\*(C`addr\*(C'\fR. Such a layout
is returned by the \f(CW\*(C`getaddrinfo\*(C'\fR named resolver.
.IP "addr => \s-1ARRAY\s0" 8
.IX Item "addr => ARRAY"
Shortcut for passing a single address to listen on; it may be passed directly
with this key, instead of in another array of its own. This should be in a
format recognised by IO::Async::OS's \f(CW\*(C`extract_addrinfo\*(C'\fR method. See also
the \f(CW\*(C`EXAMPLES\*(C'\fR section.
.PP
In named resolver mode, the \f(CW%params\fR hash takes the following keys:
.IP "service => \s-1STRING\s0" 8
.IX Item "service => STRING"
The service name to listen on.
.IP "host => \s-1STRING\s0" 8
.IX Item "host => STRING"
The hostname to listen on. Optional. Will listen on all addresses if not
supplied.
.IP "family => \s-1INT\s0" 8
.IX Item "family => INT"
.PD 0
.IP "socktype => \s-1INT\s0" 8
.IX Item "socktype => INT"
.IP "protocol => \s-1INT\s0" 8
.IX Item "protocol => INT"
.IP "flags => \s-1INT\s0" 8
.IX Item "flags => INT"
.PD
Optional. Other arguments to pass along with \f(CW\*(C`host\*(C'\fR and \f(CW\*(C`service\*(C'\fR to the
\&\f(CW\*(C`getaddrinfo\*(C'\fR call.
.IP "socktype => \s-1STRING\s0" 8
.IX Item "socktype => STRING"
Optionally may instead be one of the values \f(CW\*(Aqstream\*(Aq\fR, \f(CW\*(Aqdgram\*(Aq\fR or
\&\f(CW\*(Aqraw\*(Aq\fR to stand for \f(CW\*(C`SOCK_STREAM\*(C'\fR, \f(CW\*(C`SOCK_DGRAM\*(C'\fR or \f(CW\*(C`SOCK_RAW\*(C'\fR. This
utility is provided to allow the caller to avoid a separate \f(CW\*(C`use Socket\*(C'\fR only
for importing these constants.
.IP "on_resolve_error => \s-1CODE\s0" 8
.IX Item "on_resolve_error => CODE"
A continuation that is invoked when the name resolution attempt fails. This is
invoked in the same way as the \f(CW\*(C`on_error\*(C'\fR continuation for the \f(CW\*(C`resolve\*(C'\fR
method.
.PP
It is necessary to pass the \f(CW\*(C`socktype\*(C'\fR hint to the resolver when resolving
the host/service names into an address, as some \s-1OS\s0's \f(CW\*(C`getaddrinfo\*(C'\fR functions
require this hint. A warning is emitted if neither \f(CW\*(C`socktype\*(C'\fR nor \f(CW\*(C`protocol\*(C'\fR
hint is defined when performing a \f(CW\*(C`getaddrinfo\*(C'\fR lookup. To avoid this warning
while still specifying no particular \f(CW\*(C`socktype\*(C'\fR hint (perhaps to invoke some
OS-specific behaviour), pass \f(CW0\fR as the \f(CW\*(C`socktype\*(C'\fR value.
.PP
In either case, the following keys are also taken:
.IP "on_listen => \s-1CODE\s0" 8
.IX Item "on_listen => CODE"
Optional. A callback that is invoked when the listening socket is ready.
.Sp
.Vb 1
\& $on_listen\->( $listener )
.Ve
.IP "on_listen_error => \s-1CODE\s0" 8
.IX Item "on_listen_error => CODE"
A continuation this is invoked after all of the addresses have been tried, and
none of them succeeded. It will be passed the most significant error that
occurred, and the name of the operation it occurred in. Errors from the
\&\f(CWlisten(2)\fR syscall are considered most significant, then \f(CWbind(2)\fR, then
\&\f(CWsockopt(2)\fR, then finally \f(CWsocket(2)\fR.
.IP "on_fail => \s-1CODE\s0" 8
.IX Item "on_fail => CODE"
Optional. A callback that is invoked if a syscall fails while attempting to
create a listening sockets. It is passed the name of the syscall that failed,
the arguments that were passed to it, and the error generated. I.e.
.Sp
.Vb 1
\& $on_fail\->( "socket", $family, $socktype, $protocol, $! );
\&
\& $on_fail\->( "sockopt", $sock, $optname, $optval, $! );
\&
\& $on_fail\->( "bind", $sock, $address, $! );
\&
\& $on_fail\->( "listen", $sock, $queuesize, $! );
.Ve
.IP "queuesize => \s-1INT\s0" 8
.IX Item "queuesize => INT"
Optional. The queue size to pass to the \f(CWlisten(2)\fR calls. If not supplied,
then 3 will be given instead.
.IP "reuseaddr => \s-1BOOL\s0" 8
.IX Item "reuseaddr => BOOL"
Optional. If true or not supplied then the \f(CW\*(C`SO_REUSEADDR\*(C'\fR socket option will
be set. To prevent this, pass a false value such as 0.
.IP "v6only => \s-1BOOL\s0" 8
.IX Item "v6only => BOOL"
Optional. If defined, sets or clears the \f(CW\*(C`IPV6_V6ONLY\*(C'\fR socket option on
\&\f(CW\*(C`PF_INET6\*(C'\fR sockets. This option disables the ability of \f(CW\*(C`PF_INET6\*(C'\fR socket to
accept connections from \f(CW\*(C`AF_INET\*(C'\fR addresses. Not all operating systems allow
this option to be disabled.
.PP
As a convenience, it also supports a \f(CW\*(C`handle\*(C'\fR argument, which is passed
directly to \f(CW\*(C`configure\*(C'\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Listening on \s-1UNIX\s0 Sockets"
.IX Subsection "Listening on UNIX Sockets"
The \f(CW\*(C`handle\*(C'\fR argument can be passed an existing socket already in listening
mode, making it possible to listen on other types of socket such as \s-1UNIX\s0
sockets.
.PP
.Vb 2
\& use IO::Async::Listener;
\& use IO::Socket::UNIX;
\&
\& use IO::Async::Loop;
\& my $loop = IO::Async::Loop\->new;
\&
\& my $listener = IO::Async::Listener\->new(
\&    on_stream => sub {
\&       my ( undef, $stream ) = @_;
\&
\&       $stream\->configure(
\&          on_read => sub {
\&             my ( $self, $buffref, $eof ) = @_;
\&             $self\->write( $$buffref );
\&             $$buffref = "";
\&             return 0;
\&          },
\&       );
\&       
\&       $loop\->add( $stream );
\&    },
\& );
\&
\& $loop\->add( $listener );
\&
\& my $socket = IO::Socket::UNIX\->new(
\&    Local => "echo.sock",
\&    Listen => 1,
\& ) or die "Cannot make UNIX socket \- $!\en";
\&
\& $listener\->listen(
\&    handle => $socket,
\& );
\&
\& $loop\->run;
.Ve
.SS "Passing Plain Socket Addresses"
.IX Subsection "Passing Plain Socket Addresses"
The \f(CW\*(C`addr\*(C'\fR or \f(CW\*(C`addrs\*(C'\fR parameters should contain a definition of a plain
socket address in a form that the IO::Async::OS \f(CW\*(C`extract_addrinfo\*(C'\fR
method can use.
.PP
This example shows how to use the \f(CW\*(C`Socket\*(C'\fR functions to construct one for
\&\s-1TCP\s0 port 8001 on address 10.0.0.1:
.PP
.Vb 9
\& $listener\->listen(
\&    addr => {
\&       family   => "inet",
\&       socktype => "stream",
\&       port     => 8001,
\&       ip       => "10.0.0.1",
\&    },
\&    ...
\& );
.Ve
.PP
This example shows another way to listen on a \s-1UNIX\s0 socket, similar to the
earlier example:
.PP
.Vb 8
\& $listener\->listen(
\&    addr => {
\&       family   => "unix",
\&       socktype => "stream",
\&       path     => "echo.sock",
\&    },
\&    ...
\& );
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>