POE::Wheel::ListenAccept(3pm)

1POE::Wheel::ListenAccepUts(e3r)Contributed Perl DocumentPaOtEi:o:nWheel::ListenAccept(3)
2
3
4

NAME

6       POE::Wheel::ListenAccept - accept connections from regular listening
7       sockets
8

SYNOPSIS

10       See "SYNOPSIS" in POE::Wheel::SocketFactory for a simpler version of
11       this program.
12
13         #!perl
14
15         use warnings;
16         use strict;
17
18         use IO::Socket;
19         use POE qw(Wheel::ListenAccept Wheel::ReadWrite);
20
21         POE::Session->create(
22           inline_states => {
23             _start => sub {
24               # Start the server.
25               $_[HEAP]{server} = POE::Wheel::ListenAccept->new(
26                 Handle => IO::Socket::INET->new(
27                   LocalPort => 12345,
28                   Listen => 5,
29                 ),
30                 AcceptEvent => "on_client_accept",
31                 ErrorEvent => "on_server_error",
32               );
33             },
34             on_client_accept => sub {
35               # Begin interacting with the client.
36               my $client_socket = $_[ARG0];
37               my $io_wheel = POE::Wheel::ReadWrite->new(
38                 Handle => $client_socket,
39                 InputEvent => "on_client_input",
40                 ErrorEvent => "on_client_error",
41               );
42               $_[HEAP]{client}{ $io_wheel->ID() } = $io_wheel;
43             },
44             on_server_error => sub {
45               # Shut down server.
46               my ($operation, $errnum, $errstr) = @_[ARG0, ARG1, ARG2];
47               warn "Server $operation error $errnum: $errstr\n";
48               delete $_[HEAP]{server};
49             },
50             on_client_input => sub {
51               # Handle client input.
52               my ($input, $wheel_id) = @_[ARG0, ARG1];
53               $input =~ tr[a-zA-Z][n-za-mN-ZA-M]; # ASCII rot13
54               $_[HEAP]{client}{$wheel_id}->put($input);
55             },
56             on_client_error => sub {
57               # Handle client error, including disconnect.
58               my $wheel_id = $_[ARG3];
59               delete $_[HEAP]{client}{$wheel_id};
60             },
61           }
62         );
63
64         POE::Kernel->run();
65         exit;
66

DESCRIPTION

68       POE::Wheel::ListenAccept implements non-blocking accept() calls for
69       plain old listening server sockets.  The application provides the
70       socket, using some normal means such as socket(), IO::Socket::INET, or
71       IO::Socket::UNIX.  POE::Wheel::ListenAccept monitors the listening
72       socket and emits events whenever a new client has been accepted.
73
74       Please see POE::Wheel::SocketFactory if you need non-blocking connect()
75       or a more featureful listen/accept solution.
76
77       POE::Wheel::ListenAccept only accepts client connections.  It does not
78       read or write data, so it neither needs nor includes a put() method.
79       POE::Wheel::ReadWrite generally handles the accepted client socket.
80

PUBLIC METHODS

82   new
83       new() creates a new POE::Wheel::ListenAccept object for a given
84       listening socket.  The object will generate events relating to the
85       socket for as long as it exists.
86
87       new() accepts two required named parameters:
88
89       Handle
90
91       The "Handle" constructor parameter must contain a listening socket
92       handle.  POE::Wheel::FollowTail will monitor this socket and accept()
93       new connections as they arrive.
94
95       AcceptEvent
96
97       "AcceptEvent" is a required event name that POE::Wheel::ListenAccept
98       will emit for each accepted client socket.  "PUBLIC EVENTS" describes
99       it in detail
100
101       ErrorEvent
102
103       "ErrorEvent" is an optional event name that will be emitted whenever a
104       serious problem occurs.  Please see "PUBLIC EVENTS" for more details.
105
106   event
107       event() allows a session to change the events emitted by a wheel
108       without destroying and re-creating the object.  It accepts one or more
109       of the events listed in "PUBLIC EVENTS".  Undefined event names disable
110       those events.
111
112       Ignore connections:
113
114         sub ignore_new_connections {
115           $_[HEAP]{tailor}->event( AcceptEvent => "on_ignored_accept" );
116         }
117
118         sub handle_ignored_accept {
119           # does nothing
120         }
121
122   ID
123       The ID() method returns the wheel's unique ID.  It's useful for storing
124       the wheel in a hash.  All POE::Wheel events should be accompanied by a
125       wheel ID, which allows the wheel to be referenced in their event
126       handlers.
127
128         sub setup_listener {
129           my $wheel = POE::Wheel::ListenAccept->new(... etc  ...);
130           $_[HEAP]{listeners}{$wheel->ID} = $wheel;
131         }
132

PUBLIC EVENTS

134       POE::Wheel::ListenAccept emits a couple events.
135
136   AcceptEvent
137       "AcceptEvent" names the event that will be emitted for each newly
138       accepted client socket.  It is accompanied by three parameters:
139
140       $_[ARG0] contains the newly accepted client socket handle.  It's up to
141       the application to do something with this socket.  Most use cases
142       involve passing the socket to a POE::Wheel::ReadWrite constructor.
143
144       $_[ARG1] contains the accept() call's return value, which is often the
145       encoded remote end of the remote end of the socket.
146
147       $_[ARG2] contains the POE::Wheel::ListenAccept object's unique ID.
148       This is the same value as returned by the wheel's ID() method.
149
150       A sample "AcceptEvent" handler:
151
152         sub accept_state {
153           my ($client_socket, $remote_addr, $wheel_id) = @_[ARG0..ARG2];
154
155           # Make the remote address human readable.
156           my ($port, $packed_ip) = sockaddr_in($remote_addr);
157           my $dotted_quad = inet_ntoa($packed_ip);
158
159           print(
160             "Wheel $wheel_id accepted a connection from ",
161             "$dotted_quad port $port.\n"
162           );
163
164           # Spawn off a session to interact with the socket.
165           create_server_session($handle);
166         }
167
168   ErrorEvent
169       "ErrorEvent" names the event that will be generated whenever a new
170       connection could not be successfully accepted.  This event is
171       accompanied by four parameters:
172
173       $_[ARG0] contains the name of the operation that failed.  This usually
174       is 'accept', but be aware that it's not necessarily a function name.
175
176       $_[ARG1] and $_[ARG2] hold the numeric and stringified values of $!,
177       respectively.  POE::Wheel::ListenAccept knows how to handle EAGAIN (and
178       system-dependent equivalents), so this error will never be returned.
179
180       $_[ARG3] contains the wheel's unique ID, which may be useful for
181       shutting down one particular wheel out of a group of them.
182
183       A sample "ErrorEvent" event handler.  This assumes the wheels are saved
184       as in the "ID" example.
185
186         sub error_state {
187           my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
188           warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
189           delete $_[HEAP]{listeners}{$wheel_id};
190         }
191

BUGS

203       None known.
204

AUTHORS & COPYRIGHTS

206       Please see POE for more information about authors and contributors.
207
208
209
210perl v5.12.1                      2010-04-03       POE::Wheel::ListenAccept(3)