1POE::Component::Server:U:sTeCrP(C3o)ntributed Perl DocumPeOnEt:a:tCioomnponent::Server::TCP(3)
2
6 POE::Component::Server::TCP - a simplified TCP server
7
9 use POE qw(Component::Server::TCP);
10 ### First form just accepts connections.
12 my $acceptor_session_id = POE::Component::Server::TCP->new(
14 Port => $bind_port,
15 Address => $bind_address, # Optional.
16 Hostname => $bind_hostname, # Optional.
17 Domain => AF_INET, # Optional.
18 Alias => $session_alias, # Optional.
19 Acceptor => \&accept_handler,
20 Error => \&error_handler, # Optional.
21 );
22 ### Second form also handles connections.
24 my $acceptor_session_id = POE::Component::Server::TCP->new(
26 Port => $bind_port,
27 Address => $bind_address, # Optional.
28 Hostname => $bind_hostname, # Optional.
29 Domain => AF_INET, # Optional.
30 Alias => $session_alias, # Optional.
31 Error => \&error_handler, # Optional.
32 Args => [ "arg0", "arg1" ], # Optional.
33 Concurrency => -1, # Optional.
34 SessionType => "POE::Session::Abc", # Optional.
36 SessionParams => [ options => { debug => 1 } ], # Optional.
37 ClientInput => \&handle_client_input, # Required.
39 ClientConnected => \&handle_client_connect, # Optional.
40 ClientDisconnected => \&handle_client_disconnect, # Optional.
41 ClientError => \&handle_client_error, # Optional.
42 ClientFlushed => \&handle_client_flush, # Optional.
43 ClientFilter => POE::Filter::Xyz->new()", # Optional.
44 ClientInputFilter => POE::Filter::Xyz->new(), # Optional.
45 ClientOutputFilter => POE::Filter::Xyz->new(), # Optional.
46 ClientShutdownOnError => 0, # Optional.
47 # Optionally define other states for the client session.
49 InlineStates => { ... },
50 PackageStates => [ ... ],
51 ObjectStates => [ ... ],
52 );
53 ### Call signatures for handlers.
55 sub accept_handler {
57 my ($socket, $remote_address, $remote_port) = @_[ARG0, ARG1, ARG2];
58 }
59 sub error_handler {
61 my ($syscall_name, $error_number, $error_string) = @_[ARG0, ARG1, ARG2];
62 }
63 sub handle_client_input {
65 my $input_record = $_[ARG0];
66 }
67 sub handle_client_error {
69 my ($syscall_name, $error_number, $error_string) = @_[ARG0, ARG1, ARG2];
70 }
71 sub handle_client_connect {
73 # no special parameters
74 }
75 sub handle_client_disconnect {
77 # no special parameters
78 }
79 sub handle_client_flush {
81 # no special parameters
82 }
83 ### Reserved HEAP variables:
85 $heap->{listener} = SocketFactory (only Acceptor and Error callbacks)
87 $heap->{client} = ReadWrite (only in ClientXyz callbacks)
88 $heap->{remote_ip} = remote IP address in dotted form
89 $heap->{remote_port} = remote port
90 $heap->{remote_addr} = packed remote address and port
91 $heap->{shutdown} = shutdown flag (check to see if shutting down)
92 $heap->{shutdown_on_error} = Automatically disconnect on error.
93 ### Accepted public events.
95 # Start shutting down this connection.
97 $kernel->yield( "shutdown" );
98 # Stop listening for connections.
100 $kernel->post( server => "shutdown" );
101 # Set the maximum number of simultaneous connections.
103 $kernel->call( server => set_concurrency => $count );
104 ### Responding to a client.
106 $heap->{client}->put(@things_to_send);
108
110 The TCP server component hides a generic TCP server pattern. It uses
111 POE::Wheel::SocketFactory and POE::Wheel::ReadWrite internally, creat‐
112 ing a new session for each connection to arrive.
113 The authors hope that generic servers can be created with as little
115 work as possible. Servers with uncommon requirements may need to be
116 written using the wheel classes directly. That isn't terribly diffi‐
117 cult. A tutorial at http://poe.perl.org/ describes how.
118
120 new The new() method can accept quite a lot of parameters. It will
121 return the session ID of the accecptor session. One must use call‐
122 backs to check for errors rather than the return value of new().
123 POE::Component::Server::TCP supplies common defaults for most call‐
125 backs and handlers.
126 Acceptor => CODEREF
128 Acceptor sets a mostly obsolete callback that is expected to create
129 the connection sessions manually. Most programs should use the
130 /^Client/ callbacks instead.
131 The coderef receives its parameters directly from SocketFactory's
133 SuccessEvent. ARG0 is the accepted socket handle, suitable for giv‐
134 ing to a ReadWrite wheel. ARG1 and ARG2 contain the packed remote
135 address and numeric port, respectively. ARG3 is the SocketFactory
136 wheel's ID.
137 Acceptor => \&accept_handler
139 Acceptor lets programmers rewrite the guts of Server::TCP entirely.
141 It is not compatible with the /^Client/ callbacks.
142 Address => SCALAR
144 Address is the optional interface address the TCP server will bind
145 to. It defaults to INADDR_ANY or INADDR6_ANY when using IPv4 or
146 IPv6, respectively.
147 Address => '127.0.0.1' # Localhost IPv4
149 Address => "::1" # Localhost IPv6
150 It's passed directly to SocketFactory's BindAddress parameter, so it
152 can be in whatever form SocketFactory supports. At the time of this
153 writing, that's a dotted quad, an IPv6 address, a host name, or a
154 packed Internet address. See also the Hostname parameter.
155 Alias => SCALAR
157 Alias is an optional name by which the server's listening session
158 will be known. Messages sent to the alias will go to the listening
159 session, not the sessions that are handling active connections.
160 Alias => 'chargen'
162 Later on, the 'chargen' service can be shut down with:
164 $kernel->post( chargen => 'shutdown' );
166 Args => ARRAYREF
168 Args passes the ARRAYREF to the ClientConnected callback as ARG0. It
169 allows you to send extra information to the sessions that handle each
170 client connection.
171 ClientConnected => CODEREF
173 ClientConnected sets the callback used to notify each new client ses‐
174 sion that it is started. ClientConnected callbacks receive the usual
175 POE parameters, plus a copy of whatever was specified in the compo‐
176 nent's "Args" constructor parameter, as ARG0.
177 The ClientConnected callback will not be called within the same ses‐
179 sion context twice.
180 ClientDisconnected => CODEREF
182 ClientDisconnected sets the callback used to notify a client session
183 that the client has disconnected.
184 ClientDisconnected callbacks receive the usual POE parameters, but
186 nothing special is included.
187 ClientError => CODEREF
189 ClientError sets the callback used to notify a client session that
190 there has been an error on the connection.
191 It receives POE's usual error handler parameters: ARG0 is the name of
193 the function that failed. ARG1 is the numeric failure code ($! in
194 numeric context). ARG2 is the string failure code ($! in string con‐
195 text), and so on.
196 POE::Wheel::ReadWrite discusses the error parameters in more detail.
198 A default error handler will be provided if ClientError is omitted.
200 The default handler will log most errors to STDERR.
201 The value of ClientShutdownOnError determines whether the connection
203 will be shutdown after errors are received. It is the client shut‐
204 down, not the error, that invokes ClientDisconnected callbacks.
205 ClientFilter => SCALAR
207 ClientFilter => ARRAYREF
208 ClientFilter => OBJECT
209 ClientFilter specifies the type of filter that will parse input from
210 each client, and optionally any constructor arguments used to create
211 each filter instance.
212 It can take a class name, an arrayref, or a POE::Filter object.
214 If ClientFilter contains a SCALAR, it defines the name of the
216 POE::Filter class. Default constructor parameters will be used to
217 create instances of that filter.
218 ClientFilter => "POE::Filter::Stream",
220 If ClientFilter contains a list reference, the first item in the list
222 will be a POE::Filter class name, and the remaining items will be
223 constructor parameters for the filter. For example, this changes the
224 line separator to a vertical bar:
225 ClientFilter => [ "POE::Filter::Line", Literal => "⎪" ],
227 If ClientFilter contains an object, it will have a clone method
229 called on it each time a client connects.
230 ClientFilter => POE::Filter::Block->new()
232 ClientFilter is optional. The component will use "POE::Filter::Line"
234 if it is omitted.
235 If you supply a different value for Filter, then you must also "use"
237 that filter class.
238 ClientInputFilter => SCALAR
240 ClientInputFilter => ARRAYREF
241 ClientInputFilter => OBJECT
242 ClientOutputFilter => SCALAR
243 ClientOutputFilter => ARRAYREF
244 ClientOutputFilter => OBJECT
245 ClientInputFilter and ClientOutputFilter act like ClientFilter, but
246 they allow programs to specify different filters for input and out‐
247 put. Both must be used together.
248 Usage is the same as ClientFilter.
250 ClientInputFilter => [ "POE::Filter::Line", Literal => "⎪" ],
252 ClientOutputFilter => "POE::Filter::Stream",
253 ClientInputFilter => POE::Filter::Block->new(),
254 ClientInput => CODEREF
256 ClientInput sets a callback that will be called to handle client
257 input. The callback receives its parameters directly from Read‐
258 Write's InputEvent. ARG0 is the input record, and ARG1 is the
259 wheel's unique ID, and so on. POE::Wheel::ReadWrite discusses input
260 event handlers in more detail.
261 ClientInput => \&input_handler
263 ClientInput and Acceptor are mutually exclusive. Enabling one pro‐
265 hibits the other.
266 ClientShutdownOnError => BOOLEAN
268 ClientShutdownOnError tells the component whether to shut down client
269 sessions automatically on errors. It defaults to true. Setting it
270 to a false value (0, undef, "") turns this feature off.
271 If this option is turned off, it becomes your responsibility to deal
273 with client errors properly. Not handling them, or not destroying
274 wheels when they should be, will cause the component to spit out a
275 constant stream of errors, eventually bogging down your application
276 with dead connections that spin out of control.
277 You've been warned.
279 Domain => SCALAR
281 Specifies the domain within which communication will take place. It
282 selects the protocol family which should be used. Currently sup‐
283 ported values are AF_INET, AF_INET6, PF_INET or PF_INET6. This
284 parameter is optional and will default to AF_INET if omitted.
285 Note: AF_INET6 and PF_INET6 are supplied by the Socket6 module, which
287 is available on the CPAN. You must have Socket6 loaded before
288 POE::Component::Server::TCP will create IPv6 sockets.
289 Error => CODEREF
291 Error sets the callback that will be invoked when the server socket
292 reports an error. The callback is used to handle POE::Wheel::Socket‐
293 Factory's FailureEvent, so it receives the same parameters as dis‐
294 cussed there.
295 A default error handler will be provided if Error is omitted. The
297 default handler will log the error to STDERR and shut down the
298 server. Active connections will have the opportunity to complete
299 their transactions.
300 Hostname => SCALAR
302 Hostname is the optional non-packed name of the interface the TCP
303 server will bind to. This will always be converted via inet_aton and
304 so can either be a dotted quad or a name. If you know that you are
305 passing in text, then this parameter should be used in preference to
306 Address, to prevent confusion in the case that the hostname happens
307 to be 4 bytes in length. In the case that both are provided, then the
308 Address parameter overrides the Hostname parameter.
309 InlineStates => HASHREF
311 InlineStates holds a hashref of callbacks to handle custom events.
312 The hashref follows the same form as POE::Session->create()'s
313 inline_states parameter.
314 ObjectStates => ARRAYREF
316 ObjectStates holds a list reference of objects and the events they
317 handle. The ARRAYREF follows the same form as POE::Session->cre‐
318 ate()'s object_states parameter.
319 PackageStates => ARRAYREF
321 PackageStates holds a list reference of Perl package names and the
322 events they handle. The ARRAYREF follows the same form as POE::Ses‐
323 sion->create()'s package_states parameter.
324 Port => SCALAR
326 Port contains the port the listening socket will be bound to. It
327 defaults to INADDR_ANY, which usually lets the operating system pick
328 a port at random.
329 Port => 30023
331 SessionParams => ARRAYREF
333 SessionParams specifies additional parameters that will be passed to
334 the SessionType constructor at creation time. It must be an array
335 reference.
336 SessionParams => [ options => { debug => 1, trace => 1 } ],
338 It is important to realize that some of the arguments to SessionHan‐
340 dler may get clobbered when defining them for your SessionHandler.
341 It is advised that you stick to defining arguments in the "options"
342 hash such as trace and debug. See POE::Session for an example list of
343 options.
344 SessionType => SCALAR
346 SessionType specifies what type of sessions will be created within
347 the TCP server. It must be a scalar value.
348 SessionType => "POE::Session::MultiDispatch"
350 SessionType is optional. The component will create POE::Session
352 instances if a new type isn't specified.
353 Started => CODEREF
355 Started sets a callback that will be invoked within the main server
356 session's context. It notifies your code that the server has
357 started. Its parameters are the usual for a session's _start han‐
358 dler.
359 Started is optional.
361 Concurrency => SCALAR
363 Controls the number of connections that may be open at the same time.
364 Defaults to -1, which means unlimited number of simutaneous connec‐
365 tions. 0 means no connections. This value may be set via the
366 "set_concurrency" event, see EVENTS.
367 Note that if you define the "Acceptor" callback, you will have to
369 inform the TCP server session that a connection was closed. This is
370 done by sending a "disconnected" event to your session's parent. This
371 is only necessary if you define an "Acceptor" callback. For "Cli‐
372 entInput", it's all handled for you.
373 Example:
375 Acceptor => sub {
377 # ....
378 POE::Session->create(
379 # ....
380 inline_states => {
381 _start => sub {
382 # ....
383 # remember who our parent is
384 $_[HEAP]->{server_tcp} = $_[SENDER]->ID;
385 # ....
386 },
387 got_client_disconnect => sub {
388 # ....
389 $_[KERNEL]->post( $_[HEAP]->{server_tcp} => 'disconnected' );
390 # ....
391 }
392 }
393 );
394 }
395
397 It's possible to manipulate a TCP server component by sending it mes‐
398 sages.
399 shutdown
401 Shuts down the TCP server. This entails destroying the SocketFactory
402 that's listening for connections and removing the TCP server's alias,
403 if one is set.
404 Active connections are not shut down until they disconnect.
406 disconnected
408 Inform the TCP server that a connection was closed. This is only
409 necessary when using "Concurrency" is set and you are using an Accep‐
410 tor callback.
411 set_concurrency
413 Set the number of simultaneous connections. See Concurrency above.
414 $kernel->call( "tcp_server_alias", "set_concurrency", $max_count );
416
418 POE::Component::Client::TCP, POE::Wheel::SocketFactory,
419 POE::Wheel::ReadWrite, POE::Filter
420
422 This looks nothing like what Ann envisioned.
423 This component currently does not accept many of the options that
425 POE::Wheel::SocketFactory does.
426 This component will not bind to several addresses at once. This may be
428 a limitation in SocketFactory, but it's not by design.
429 This component needs more complex error handling which appends for con‐
431 struction errors and replaces for runtime errors, instead of replacing
432 for all.
433 Some use cases require different session classes for the listener and
435 the connection handlers. This isn't currently supported. Please send
436 patches. :)
437
439 POE::Component::Server::TCP is Copyright 2000-2006 by Rocco Caputo.
440 All rights are reserved. POE::Component::Server::TCP is free software,
441 and it may be redistributed and/or modified under the same terms as
442 Perl itself.
443 POE::Component::Server::TCP is based on code, used with permission,
445 from Ann Barcomb <kudra@domaintje.com>.
446 POE::Component::Server::TCP is based on code, used with permission,
448 from Jos Boumans <kane@cpan.org>.
449perl v5.8.8 2006-09-01 POE::Component::Server::TCP(3)