.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 3" .TH POE::Wheel::ListenAccept 3 2024-07-13 "perl v5.38.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 POE::Wheel::ListenAccept \- accept connections from regular listening sockets .SH SYNOPSIS .IX Header "SYNOPSIS" See "SYNOPSIS" 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. "PUBLIC EVENTS" 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 "PUBLIC EVENTS" 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 "PUBLIC EVENTS". 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 ID .IX Subsection "ID" The \fBID()\fR method returns the wheel's unique ID. It's useful for storing the wheel in a hash. All POE::Wheel events should be accompanied by a wheel ID, 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 ID. This is the same value as returned by the wheel's \fBID()\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 EAGAIN (and system-dependent equivalents), so this error will never be returned. .PP \&\f(CW$_[ARG3]\fR contains the wheel's unique ID, 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 "ID" 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 SEE ALSO section in POE contains a table of contents covering the entire POE distribution. .SH BUGS .IX Header "BUGS" None known. .SH "AUTHORS & COPYRIGHTS" .IX Header "AUTHORS & COPYRIGHTS" Please see POE for more information about authors and contributors.