.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POE::Wheel::ListenAccept 3pm"
.TH POE::Wheel::ListenAccept 3pm "2020-02-07" "perl v5.30.0" "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"
POE::Wheel::ListenAccept \- accept connections from regular listening sockets
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
See \*(L"\s-1SYNOPSIS\*(R"\s0 in POE::Wheel::SocketFactory for a simpler version of
this program.
.PP
.Vb 1
\&  #!perl
\&
\&  use warnings;
\&  use strict;
\&
\&  use IO::Socket;
\&  use POE qw(Wheel::ListenAccept Wheel::ReadWrite);
\&
\&  POE::Session\->create(
\&    inline_states => {
\&      _start => sub {
\&        # Start the server.
\&        $_[HEAP]{server} = POE::Wheel::ListenAccept\->new(
\&          Handle => IO::Socket::INET\->new(
\&            LocalPort => 12345,
\&            Listen => 5,
\&          ),
\&          AcceptEvent => "on_client_accept",
\&          ErrorEvent => "on_server_error",
\&        );
\&      },
\&      on_client_accept => sub {
\&        # Begin interacting with the client.
\&        my $client_socket = $_[ARG0];
\&        my $io_wheel = POE::Wheel::ReadWrite\->new(
\&          Handle => $client_socket,
\&          InputEvent => "on_client_input",
\&          ErrorEvent => "on_client_error",
\&        );
\&        $_[HEAP]{client}{ $io_wheel\->ID() } = $io_wheel;
\&      },
\&      on_server_error => sub {
\&        # Shut down server.
\&        my ($operation, $errnum, $errstr) = @_[ARG0, ARG1, ARG2];
\&        warn "Server $operation error $errnum: $errstr\en";
\&        delete $_[HEAP]{server};
\&      },
\&      on_client_input => sub {
\&        # Handle client input.
\&        my ($input, $wheel_id) = @_[ARG0, ARG1];
\&        $input =~ tr[a\-zA\-Z][n\-za\-mN\-ZA\-M]; # ASCII rot13
\&        $_[HEAP]{client}{$wheel_id}\->put($input);
\&      },
\&      on_client_error => sub {
\&        # Handle client error, including disconnect.
\&        my $wheel_id = $_[ARG3];
\&        delete $_[HEAP]{client}{$wheel_id};
\&      },
\&    }
\&  );
\&
\&  POE::Kernel\->run();
\&  exit;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
POE::Wheel::ListenAccept implements non-blocking \fBaccept()\fR calls for
plain old listening server sockets.  The application provides the
socket, using some normal means such as \fBsocket()\fR, IO::Socket::INET, or
IO::Socket::UNIX.  POE::Wheel::ListenAccept monitors the listening
socket and emits events whenever a new client has been accepted.
.PP
Please see POE::Wheel::SocketFactory if you need non-blocking
\&\fBconnect()\fR or a more featureful listen/accept solution.
.PP
POE::Wheel::ListenAccept only accepts client connections.  It does not
read or write data, so it neither needs nor includes a \fBput()\fR method.
POE::Wheel::ReadWrite generally handles the accepted client socket.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.SS "new"
.IX Subsection "new"
\&\fBnew()\fR creates a new POE::Wheel::ListenAccept object for a given
listening socket.  The object will generate events relating to the
socket for as long as it exists.
.PP
\&\fBnew()\fR accepts two required named parameters:
.PP
\fIHandle\fR
.IX Subsection "Handle"
.PP
The \f(CW\*(C`Handle\*(C'\fR constructor parameter must contain a listening socket
handle.  POE::Wheel::FollowTail will monitor this socket and \fBaccept()\fR
new connections as they arrive.
.PP
\fIAcceptEvent\fR
.IX Subsection "AcceptEvent"
.PP
\&\f(CW\*(C`AcceptEvent\*(C'\fR is a required event name that POE::Wheel::ListenAccept
will emit for each accepted client socket.  \*(L"\s-1PUBLIC EVENTS\*(R"\s0
describes it in detail
.PP
\fIErrorEvent\fR
.IX Subsection "ErrorEvent"
.PP
\&\f(CW\*(C`ErrorEvent\*(C'\fR is an optional event name that will be emitted whenever
a serious problem occurs.  Please see \*(L"\s-1PUBLIC EVENTS\*(R"\s0 for more
details.
.SS "event"
.IX Subsection "event"
\&\fBevent()\fR allows a session to change the events emitted by a wheel
without destroying and re-creating the object.  It accepts one or more
of the events listed in \*(L"\s-1PUBLIC EVENTS\*(R"\s0.  Undefined event names
disable those events.
.PP
Ignore connections:
.PP
.Vb 3
\&  sub ignore_new_connections {
\&    $_[HEAP]{tailor}\->event( AcceptEvent => "on_ignored_accept" );
\&  }
\&
\&  sub handle_ignored_accept {
\&    # does nothing
\&  }
.Ve
.SS "\s-1ID\s0"
.IX Subsection "ID"
The \s-1\fBID\s0()\fR method returns the wheel's unique \s-1ID.\s0  It's useful for
storing the wheel in a hash.  All POE::Wheel events should be
accompanied by a wheel \s-1ID,\s0 which allows the wheel to be referenced in
their event handlers.
.PP
.Vb 4
\&  sub setup_listener {
\&    my $wheel = POE::Wheel::ListenAccept\->new(... etc  ...);
\&    $_[HEAP]{listeners}{$wheel\->ID} = $wheel;
\&  }
.Ve
.SH "PUBLIC EVENTS"
.IX Header "PUBLIC EVENTS"
POE::Wheel::ListenAccept emits a couple events.
.SS "AcceptEvent"
.IX Subsection "AcceptEvent"
\&\f(CW\*(C`AcceptEvent\*(C'\fR names the event that will be emitted for each newly
accepted client socket.  It is accompanied by three parameters:
.PP
\&\f(CW$_[ARG0]\fR contains the newly accepted client socket handle.  It's up
to the application to do something with this socket.  Most use cases
involve passing the socket to a POE::Wheel::ReadWrite constructor.
.PP
\&\f(CW$_[ARG1]\fR contains the \fBaccept()\fR call's return value, which is often
the encoded remote end of the remote end of the socket.
.PP
\&\f(CW$_[ARG2]\fR contains the POE::Wheel::ListenAccept object's unique \s-1ID.\s0
This is the same value as returned by the wheel's \s-1\fBID\s0()\fR method.
.PP
A sample \f(CW\*(C`AcceptEvent\*(C'\fR handler:
.PP
.Vb 2
\&  sub accept_state {
\&    my ($client_socket, $remote_addr, $wheel_id) = @_[ARG0..ARG2];
\&
\&    # Make the remote address human readable.
\&    my ($port, $packed_ip) = sockaddr_in($remote_addr);
\&    my $dotted_quad = inet_ntoa($packed_ip);
\&
\&    print(
\&      "Wheel $wheel_id accepted a connection from ",
\&      "$dotted_quad port $port.\en"
\&    );
\&
\&    # Spawn off a session to interact with the socket.
\&    create_server_session($handle);
\&  }
.Ve
.SS "ErrorEvent"
.IX Subsection "ErrorEvent"
\&\f(CW\*(C`ErrorEvent\*(C'\fR names the event that will be generated whenever a new
connection could not be successfully accepted.  This event is
accompanied by four parameters:
.PP
\&\f(CW$_[ARG0]\fR contains the name of the operation that failed.  This
usually is 'accept', but be aware that it's not necessarily a function
name.
.PP
\&\f(CW$_[ARG1]\fR and \f(CW$_[ARG2]\fR hold the numeric and stringified values
of \f(CW$!\fR, respectively.  POE::Wheel::ListenAccept knows how to handle
\&\s-1EAGAIN\s0 (and system-dependent equivalents), so this error will never be
returned.
.PP
\&\f(CW$_[ARG3]\fR contains the wheel's unique \s-1ID,\s0 which may be useful for
shutting down one particular wheel out of a group of them.
.PP
A sample \f(CW\*(C`ErrorEvent\*(C'\fR event handler.  This assumes the wheels are
saved as in the \*(L"\s-1ID\*(R"\s0 example.
.PP
.Vb 5
\&  sub error_state {
\&    my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
\&    warn "Wheel $wheel_id generated $operation error $errnum: $errstr\en";
\&    delete $_[HEAP]{listeners}{$wheel_id};
\&  }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
POE::Wheel describes the basic operations of all wheels in more
depth.  You need to know this.
.PP
POE::Wheel::ReadWrite for one possible way to handle clients once
you have their sockets.
.PP
The \s-1SEE ALSO\s0 section in \s-1POE\s0 contains a table of contents covering
the entire \s-1POE\s0 distribution.
.SH "BUGS"
.IX Header "BUGS"
None known.
.SH "AUTHORS & COPYRIGHTS"
.IX Header "AUTHORS & COPYRIGHTS"
Please see \s-1POE\s0 for more information about authors and contributors.