1POE::Component::Server:U:sTeCrP(C3o)ntributed Perl DocumPeOnEt:a:tCioomnponent::Server::TCP(3)
2
3
4

NAME

6       POE::Component::Server::TCP - a simplified TCP server
7

SYNOPSIS

9         use POE qw(Component::Server::TCP);
10
11         ### First form just accepts connections.
12
13         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
23         ### Second form also handles connections.
24
25         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
35           SessionType   => "POE::Session::Abc",           # Optional.
36           SessionParams => [ options => { debug => 1 } ], # Optional.
37
38           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
48           # Optionally define other states for the client session.
49           InlineStates  => { ... },
50           PackageStates => [ ... ],
51           ObjectStates  => [ ... ],
52         );
53
54         ### Call signatures for handlers.
55
56         sub accept_handler {
57           my ($socket, $remote_address, $remote_port) = @_[ARG0, ARG1, ARG2];
58         }
59
60         sub error_handler {
61           my ($syscall_name, $error_number, $error_string) = @_[ARG0, ARG1, ARG2];
62         }
63
64         sub handle_client_input {
65           my $input_record = $_[ARG0];
66         }
67
68         sub handle_client_error {
69           my ($syscall_name, $error_number, $error_string) = @_[ARG0, ARG1, ARG2];
70         }
71
72         sub handle_client_connect {
73           # no special parameters
74         }
75
76         sub handle_client_disconnect {
77           # no special parameters
78         }
79
80         sub handle_client_flush {
81           # no special parameters
82         }
83
84         ### Reserved HEAP variables:
85
86         $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
94         ### Accepted public events.
95
96         # Start shutting down this connection.
97         $kernel->yield( "shutdown" );
98
99         # Stop listening for connections.
100         $kernel->post( server => "shutdown" );
101
102         # Set the maximum number of simultaneous connections.
103         $kernel->call( server => set_concurrency => $count );
104
105         ### Responding to a client.
106
107         $heap->{client}->put(@things_to_send);
108

DESCRIPTION

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
114       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

CONSTRUCTOR PARAMETERS

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
124           POE::Component::Server::TCP supplies common defaults for most call‐
125           backs and handlers.
126
127       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
132         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
138           Acceptor => \&accept_handler
139
140         Acceptor lets programmers rewrite the guts of Server::TCP entirely.
141         It is not compatible with the /^Client/ callbacks.
142
143       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
148           Address => '127.0.0.1'   # Localhost IPv4
149           Address => "::1"         # Localhost IPv6
150
151         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
156       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
161           Alias => 'chargen'
162
163         Later on, the 'chargen' service can be shut down with:
164
165           $kernel->post( chargen => 'shutdown' );
166
167       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
172       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
178         The ClientConnected callback will not be called within the same ses‐
179         sion context twice.
180
181       ClientDisconnected => CODEREF
182         ClientDisconnected sets the callback used to notify a client session
183         that the client has disconnected.
184
185         ClientDisconnected callbacks receive the usual POE parameters, but
186         nothing special is included.
187
188       ClientError => CODEREF
189         ClientError sets the callback used to notify a client session that
190         there has been an error on the connection.
191
192         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
197         POE::Wheel::ReadWrite discusses the error parameters in more detail.
198
199         A default error handler will be provided if ClientError is omitted.
200         The default handler will log most errors to STDERR.
201
202         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
206       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
213         It can take a class name, an arrayref, or a POE::Filter object.
214
215         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
219           ClientFilter => "POE::Filter::Stream",
220
221         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
226           ClientFilter => [ "POE::Filter::Line", Literal => "⎪" ],
227
228         If ClientFilter contains an object, it will have a clone method
229         called on it each time a client connects.
230
231           ClientFilter => POE::Filter::Block->new()
232
233         ClientFilter is optional.  The component will use "POE::Filter::Line"
234         if it is omitted.
235
236         If you supply a different value for Filter, then you must also "use"
237         that filter class.
238
239       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
249         Usage is the same as ClientFilter.
250
251           ClientInputFilter  => [ "POE::Filter::Line", Literal => "⎪" ],
252           ClientOutputFilter => "POE::Filter::Stream",
253           ClientInputFilter  => POE::Filter::Block->new(),
254
255       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
262           ClientInput => \&input_handler
263
264         ClientInput and Acceptor are mutually exclusive.  Enabling one pro‐
265         hibits the other.
266
267       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
272         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
278         You've been warned.
279
280       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
286         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
290       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
296         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
301       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
310       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
315       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
320       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
325       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
330           Port => 30023
331
332       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
337           SessionParams => [ options => { debug => 1, trace => 1 } ],
338
339         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
345       SessionType => SCALAR
346         SessionType specifies what type of sessions will be created within
347         the TCP server.  It must be a scalar value.
348
349           SessionType => "POE::Session::MultiDispatch"
350
351         SessionType is optional.  The component will create POE::Session
352         instances if a new type isn't specified.
353
354       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
360         Started is optional.
361
362       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
368         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
374         Example:
375
376           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

EVENTS

397       It's possible to manipulate a TCP server component by sending it mes‐
398       sages.
399
400       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
405         Active connections are not shut down until they disconnect.
406
407       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
412       set_concurrency
413         Set the number of simultaneous connections.  See Concurrency above.
414
415           $kernel->call( "tcp_server_alias", "set_concurrency", $max_count );
416

SEE ALSO

418       POE::Component::Client::TCP, POE::Wheel::SocketFactory,
419       POE::Wheel::ReadWrite, POE::Filter
420

BUGS

422       This looks nothing like what Ann envisioned.
423
424       This component currently does not accept many of the options that
425       POE::Wheel::SocketFactory does.
426
427       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
430       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
434       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

AUTHORS & COPYRIGHTS

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
444       POE::Component::Server::TCP is based on code, used with permission,
445       from Ann Barcomb <kudra@domaintje.com>.
446
447       POE::Component::Server::TCP is based on code, used with permission,
448       from Jos Boumans <kane@cpan.org>.
449
450
451
452perl v5.8.8                       2006-09-01    POE::Component::Server::TCP(3)
Impressum