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         #!perl
10
11         use warnings;
12         use strict;
13
14         use POE qw(Component::Server::TCP);
15
16         POE::Component::Server::TCP->new(
17           Port => 12345,
18           ClientConnected => sub {
19             print "got a connection from $_[HEAP]{remote_ip}\n";
20             $_[HEAP]{client}->put("Smile from the server!");
21           },
22           ClientInput => sub {
23             my $client_input = $_[ARG0];
24             $client_input =~ tr[a-zA-Z][n-za-mN-ZA-M];
25             $_[HEAP]{client}->put($client_input);
26           },
27         );
28
29         POE::Kernel->run;
30         exit;
31

DESCRIPTION

33       POE::Component::Server::TCP implements a generic multi-Session server.
34       Simple services may be put together in a few lines of code.  For
35       example, a server that echoes input back to the client:
36
37         use POE qw(Component::Server::TCP);
38         POE::Component::Server::TCP->new(
39           Port => 12345,
40           ClientInput => sub { $_[HEAP]{client}->put($_[ARG0]) },
41         );
42         POE::Kernel->run();
43
44   Accepting Connections Yourself
45       POE::Component::Server::TCP has a default mode where it accepts new
46       connections and creates the sessions to handle them.  Programs can do
47       this themselves by providing their own "Acceptor" callbacks.  See
48       "Acceptor" for details.
49
50   Master Listener Session
51       At creation time, POE::Component::Server::TCP starts one POE::Session
52       to listen for new connections.  The component's "Alias" refers to this
53       master session.
54
55       If "Acceptor" is specified, then it's up to that callback to deal with
56       newly accepted sockets.  Its parameters are that of
57       POE::Wheel::SocketFactory's "SuccessEvent".
58
59       Otherwise, the default "Acceptor" callback will start a new session to
60       handle each connection.  These child sessions do not have their own
61       aliases, but their "ClientConnected" and "ClientDisconnected" callbacks
62       may be used to register and unregister the sessions with a shared
63       namespace, such as a hash keyed on session IDs, or an object that
64       manages such a hash.
65
66         my %client_namespace;
67
68         sub handle_client_connected {
69           my $client_session_id = $_[SESSION]->ID;
70           $client_namespace{$client_session_id} = \%anything;
71         }
72
73         sub handle_client_disconnected {
74           my $client_session_id = $_[SESSION]->ID;
75           $client_namespace{$client_session_id} = \%anything;
76         }
77
78       The component's "Started" callback is invoked at the end of the master
79       session's start-up routine.  The @_[ARG0..$#_] parameters are set to a
80       copy of the values in the server's "ListenerArgs" constructor
81       parameter.  The other parameters are standard for POE::Session's _start
82       handlers.
83
84       The component's "Stopped" callback is invoked at the beginning of the
85       master session's _stop routine. The parameters are standard for
86       POE::Session's _stop handlers.
87
88       The component's "Error" callback is invoked when the server has a
89       problem listening for connections.  "Error" may also be called if the
90       component's default acceptor has trouble accepting a connection.
91       "Error" receives the usual ones for "FailureEvent" in
92       POE::Wheel::SocketFactory and "ErrorEvent" in POE::Wheel::ReadWrite.
93
94   Default Child Connection Sessions
95       If "Acceptor" isn't specified, POE::Component::Server::TCP's default
96       handler will start a new session for each new client connection.  As
97       mentioned above, these child sessions have no aliases of their own, but
98       they may set aliases or register themselves another way during their
99       "ClientConnected" and "ClientDisconnected" callbacks.
100
101       It can't be stressed enough that the following callbacks are executed
102       within the context of dynamic child sessions---one per client
103       connection---and not in the master listening session.  This has been a
104       major point of confusion.  We welcome suggestions for making this
105       clearer.
106
107       The component's "ClientInput" callback defines how child sessions will
108       handle input from their clients.  Its parameters are that of
109       POE::Wheel::ReadWrite's "InputEvent".
110
111       As mentioned "ClientConnected" is called at the end of the child
112       session's "_start" routine.  The "ClientConneted" callback receives the
113       same parameters as the client session's _start does.  The arrayref
114       passed to the constructor's "Args" parameter is flattened and included
115       in "ClientConnected"'s parameters as @_[ARG0..$#_].
116
117         sub handle_client_connected {
118           my @constructor_args = @_[ARG0..$#_];
119           ...
120         }
121
122       "ClientPreConnect" is called before "ClientConnected", and its purpose
123       is to allow programs to reject connections or condition sockets before
124       they're given to POE::Wheel::ReadWrite for management.
125
126       The "ClientPreConnect" handler is called with the client socket in
127       $_[ARG0], and its return value is significant.  It must return a valid
128       client socket if the connection is acceptable.  It must return undef to
129       reject the connection.
130
131       Most $_[HEAP] values are valid in the "ClientPreConnect" handler.
132       Obviously, $_[HEAP]{client} is not because that wheel hasn't been
133       created yet.
134
135       In the following example, the "ClientPreConnect" handler returns the
136       client socket after it has been upgraded to an SSL connection.
137
138         sub handle_client_pre_connect {
139
140           # Make sure the remote address and port are valid.
141           return undef unless validate(
142             $_[HEAP]{remote_ip}, $_[HEAP]{remote_port}
143           );
144
145           # SSLify the socket, which is in $_[ARG0].
146           my $socket = eval { Server_SSLify($_[ARG0]) };
147           return undef if $@;
148
149           # Return the SSL-ified socket.
150           return $socket;
151         }
152
153       "ClientDisconnected" is called when the client has disconnected, either
154       because the remote socket endpoint has closed or the local endpoint has
155       been closed by the server.  This doesn't mean the client's session has
156       ended, but the session most likely will very shortly.
157       "ClientDisconnected" is called from a couple disparate places within
158       the component, so its parameters are neither consistent nor generally
159       useful.
160
161       "ClientError" is called when an error has occurred on the socket.  Its
162       parameters are those of POE::Wheel::ReadWrite's "ErrorEvent".
163
164       "ClientFlushed" is called when all pending output has been flushed to
165       the client socket.  Its parameters come from POE::Wheel::ReadWrite's
166       "ErrorEvent".
167
168   Performance Considerations
169       This ease of use comes at a price: POE::Component::Server::TCP often
170       performs significantly slower than a comparable server written with
171       POE::Wheel::SocketFactory and POE::Wheel::ReadWrite.
172
173       If performance is your primary goal, POE::Kernel's select_read() and
174       select_write() perform about the same as IO::Select, but your code will
175       be portable across every event loop POE supports.
176
177   Special Needs Considerations
178       POE::Component::Server::TCP is written to be easy for the most common
179       use cases.  Programs with more special needs should consider using
180       POE::Wheel::SocketFactory and POE::Wheel::ReadWrite instead.  These are
181       lower-level modules, and using them requires more effort.  They are
182       more flexible and customizable, however.
183

PUBLIC METHODS

185   new
186       new() starts a server based on POE::Component::Server::TCP and returns
187       a session ID for the master listening session.  All error handling is
188       done within the server, via the "Error" and "ClientError" callbacks.
189
190       The server may be shut down by posting a "shutdown" event to the master
191       session, either by its ID or the name given to it by the "Alias"
192       parameter.
193
194       POE::Component::Server::TCP does a lot of work in its constructor.  The
195       design goal is to push as much overhead into one-time construction so
196       that ongoing run-time has less overhead.  Because of this, the server's
197       constructor can take quite a daunting number of parameters.
198
199       POE::Component::Server::TCP always returns a POE::Session ID for the
200       session that will be listening for new connections.
201
202       Many of the constructor parameters have been previously described.
203       They are covered briefly again below.
204
205       Server Session Configuration
206
207       These constructor parameters affect POE::Component::Server::TCP's main
208       listening session.
209
210       Acceptor
211
212       "Acceptor" defines a CODE reference that POE::Wheel::SocketFactory's
213       "SuccessEvent" will trigger to handle new connections.  Therefore the
214       parameters passed to "Acceptor" are identical to those given to
215       "SuccessEvent".
216
217       "Acceptor" is optional; the default handler will create a new session
218       for each connection.  All the "Client" constructor parameters are used
219       to customize this session.  In other words, "ClientInput" and such are
220       not used when "Acceptor" is set.
221
222       The default "Acceptor" adds significant convenience and flexibility to
223       POE::Component::Server::TCP, but it's not always a good fit for every
224       application.  In some cases, a custom "Acceptor" or even rolling one's
225       own server with POE::Wheel::SocketFactory and POE::Wheel::ReadWrite may
226       be better and/or faster.
227
228         Acceptor => sub {
229           my ($socket, $remote_address, $remote_port) = @_[ARG0..ARG2];
230           # Set up something to interact with the client.
231         }
232
233       Address
234
235       "Address" defines a single interface address the server will bind to.
236       It defaults to INADDR_ANY or INADDR6_ANY, when using IPv4 or IPv6,
237       respectively.  It is often used with "Port".
238
239       The value in "Address" is passed to POE::Wheel::SocketFactory's
240       "BindAddress" parameter, so it may be in whatever form that module
241       supports.  At the time of this writing, that may be a dotted IPv4 quad,
242       an IPv6 address, a host name, or a packed Internet address.  See also
243       "Hostname".
244
245         Address => '127.0.0.1'   # Localhost IPv4
246         Address => "::1"         # Localhost IPv6
247
248       Alias
249
250       "Alias" is an optional name that will be given to the server's master
251       listening session.  Events sent to this name will not be delivered to
252       individual connections.
253
254       The server's "Alias" may be important if it's necessary to shut a
255       server down.
256
257         sub sigusr1_handler {
258           $_[KERNEL]->post(chargen_server => 'shutdown');
259           $_[KERNEL]->sig_handled();
260         }
261
262       Concurrency
263
264       "Concurrency" controls how many connections may be active at the same
265       time.  It defaults to -1, which allows POE::Component::Server::TCP to
266       accept concurrent connections until the process runs out of resources.
267
268       Setting "Concurrency" to 0 prevents the server from accepting new
269       connections.  This may be useful if a server must perform lengthy
270       initialization before allowing connections.  When the initialization
271       finishes, it can yield(set_concurrency => -1) to enable connections.
272       Likewise, a running server may yield(set_concurrency => 0) or any other
273       number to dynamically tune its concurrency.  See "EVENTS" for more
274       about the set_concurrency event.
275
276       Note: For "Concurrency" to work with a custom "Acceptor", the server's
277       listening session must receive a "disconnected" event whenever clients
278       disconnect.  Otherwise the listener cannot mediate between its
279       connections.
280
281       Example:
282
283         Acceptor => sub {
284           # ....
285           POE::Session->create(
286             # ....
287             inline_states => {
288               _start => sub {
289                 # ....
290                 # remember who our parent is
291                 $_[HEAP]->{server_tcp} = $_[SENDER]->ID;
292                 # ....
293               },
294               got_client_disconnect => sub {
295                 # ....
296                 $_[KERNEL]->post( $_[HEAP]->{server_tcp} => 'disconnected' );
297                 # ....
298               }
299             }
300           );
301         }
302
303       Domain
304
305       "Domain" sets the address or protocol family within which to operate.
306       The "Domain" may be any value that POE::Wheel::SocketFactory supports.
307       AF_INET (Internet address space) is used by default.
308
309       Use AF_INET6 for IPv6 support.  This constant is exported by Socket or
310       Socket6, depending on your version of Perl. Also be sure to have
311       Socket::GetAddrInfo installed, which is required by
312       POE::Wheel::SocketFactory for IPv6 support.
313
314       Error
315
316       "Error" is the callback that will be invoked when the server socket
317       reports an error.  The Error callback will be used to handle
318       POE::Wheel::SocketFactory's FailureEvent, so it will receive the same
319       parameters as discussed there.
320
321       A default error handler will be provided if Error is omitted.  The
322       default handler will log the error to STDERR and shut down the server.
323       Active connections will be permitted to complete their transactions.
324
325         Error => sub {
326           my ($syscall_name, $err_num, $err_str) = @_[ARG0..ARG2];
327           # Handle the error.
328         }
329
330       Hostname
331
332       "Hostname" is the optional non-packed name of the interface the TCP
333       server will bind to.  The hostname will always be resolved via
334       inet_aton() and so can either be a dotted quad or a name.  Name
335       resolution is a one-time start-up action; there are no ongoing run-time
336       penalties for using it.
337
338       "Hostname" guarantees name resolution, where "Address" does not.  It's
339       therefore preferred to use "Hostname" in cases where resolution must
340       always be done.
341
342       InlineStates
343
344       "InlineStates" is optional.  If specified, it must hold a hashref of
345       named callbacks.  Its syntax is that of POE:Session->create()'s
346       inline_states parameter.
347
348       Remember: These InlineStates handlers will be added to the client
349       sessions, not to the main listening session.  A yield() in the listener
350       will not reach these handlers.
351
352       If POE::Kernel::ASSERT_USAGE is enabled, the constructor will croak()
353       if it detects a state that it uses internally. For example, please use
354       the "Started" and "Stopped" callbacks if you want to specify your own
355       "_start" and "_stop" events respectively.
356
357       ObjectStates
358
359       If "ObjectStates" is specified, it must holde an arrayref of objects
360       and the events they will handle.  The arrayref must follow the syntax
361       for POE::Session->create()'s object_states parameter.
362
363       Remember: These ObjectStates handlers will be added to the client
364       sessions, not to the main listening session.  A yield() in the listener
365       will not reach these handlers.
366
367       If POE::Kernel::ASSERT_USAGE is enabled, the constructor will croak()
368       if it detects a state that it uses internally. For example, please use
369       the "Started" and "Stopped" callbacks if you want to specify your own
370       "_start" and "_stop" events respectively.
371
372       PackageStates
373
374       When the optional "PackageStates" is set, it must hold an arrayref of
375       package names and the events they will handle  The arrayref must follow
376       the syntax for POE::Session->create()'s package_states parameter.
377
378       Remember: These PackageStates handlers will be added to the client
379       sessions, not to the main listening session.  A yield() in the listener
380       will not reach these handlers.
381
382       If POE::Kernel::ASSERT_USAGE is enabled, the constructor will croak()
383       if it detects a state that it uses internally. For example, please use
384       the "Started" and "Stopped" callbacks if you want to specify your own
385       "_start" and "_stop" events respectively.
386
387       Port
388
389       "Port" contains the port the listening socket will be bound to.  It
390       defaults to 0, which usually lets the operating system pick a port at
391       random.
392
393         Port => 30023
394
395       It is often used with "Address".
396
397       Started
398
399       "Started" sets an optional callback that will be invoked within the
400       main server session's context.  It notifies the server that it has
401       fully started.  The callback's parameters are the usual for a session's
402       _start handler.
403
404       Stopped
405
406       "Stopped" sets an optional callback that will be invoked within the
407       main server session's context.  It notifies the server that it has
408       fully stopped.  The callback's parameters are the usual for a session's
409       _stop handler.
410
411       ListenerArgs
412
413       "ListenerArgs" is passed to the listener session as the "args"
414       parameter.  In other words, it must be an arrayref, and the values are
415       passed into the "Started" handler as ARG0, ARG1, etc.
416
417       Connection Session Configuration
418
419       These constructor parameters affect the individual sessions that
420       interact with established connections.
421
422       ClientArgs
423
424       "ClientArgs" is optional.  When specified, it holds an ARRAYREF that
425       will be expanded one level and passed to the "ClientConnected" callback
426       in @_[ARG0..$#_].
427
428       ClientConnected
429
430       Each new client connection is handled by a new POE::Session instance.
431       "ClientConnected" is a callback that notifies the application when a
432       client's session is started and ready for operation.  Banners are often
433       sent to the remote client from this callback.
434
435       The @_[ARG0..$#_] parameters to "ClientConnected" are a copy of the
436       values in the "ClientArgs" constructor parameter's array reference.
437       The other @_ members are standard for a POE::Session _start handler.
438
439       "ClientConnected" is called once per session start-up.  It will never
440       be called twice for the same connection.
441
442         ClientConnected => sub {
443           $_[HEAP]{client}->put("Hello, client!");
444           # Other client initialization here.
445         },
446
447       ClientDisconnected
448
449       "ClientDisconnected" is a callback that will be invoked when the client
450       disconnects or has been disconnected by the server.  It's useful for
451       cleaning up global client information, such as chat room structures.
452       "ClientDisconnected" callbacks receive the usual POE parameters, but
453       nothing special is included.
454
455         ClientDisconnected => sub {
456           warn "Client disconnected"; # log it
457         }
458
459       ClientError
460
461       The "ClientError" callback is invoked when a client socket reports an
462       error.  "ClientError" is called with POE's usual parameters, plus the
463       common error parameters: $_[ARG0] describes what was happening at the
464       time of failure.  $_[ARG1] and $_[ARG2] contain the numeric and string
465       versions of $!, respectively.
466
467       "ClientError" is optional.  If omitted, POE::Component::Server::TCP
468       will provide a default callback that logs most errors to STDERR.
469
470       If "ClientShutdownOnError" is set, the connection will be shut down
471       after "ClientError" returns.  If "ClientDisconnected" is specified, it
472       will be called as the client session is cleaned up.
473
474       "ClientError" is triggered by POE::Wheel::ReadWrite's ErrorEvent, so it
475       follows that event's form.  Please see the ErrorEvent documentation in
476       POE::Wheel::ReadWrite for more details.
477
478         ClientError => sub {
479           my ($syscall_name, $error_num, $error_str) = @_[ARG0..ARG2];
480           # Handle the client error here.
481         }
482
483       ClientFilter
484
485       "ClientFilter" specifies the POE::Filter object or class that will
486       parse input from each client and serialize output before it's sent to
487       each client.
488
489       "ClientFilter" may be a SCALAR, in which case it should name the
490       POE::Filter class to use.  Each new connection will be given a freshly
491       instantiated filter of that class.  No constructor parameters will be
492       passed.
493
494         ClientFilter => "POE::Filter::Stream",
495
496       Some filters require constructor parameters.  These may be specified by
497       an ARRAYREF.  The first element is the POE::Filter class name, and
498       subsequent elements are passed to the class' constructor.
499
500         ClientFilter => [ "POE::Filter::Line", Literal => "\n" ],
501
502       "ClientFilter" may also be given an archetypical POE::Filter OBJECT.
503       In this case, each new client session will receive a clone() of the
504       given object.
505
506         ClientFilter => POE::Filter::Line->new(Literal => "\n"),
507
508       "ClientFilter" is optional.  The component will use "POE::Filter::Line"
509       if it is omitted.  There is "ClientInputFilter" and
510       "ClientOutputFilter" if you want to specify a different filter for both
511       directions.
512
513       Filter modules are not automatically loaded.  Be sure that the program
514       loads the class before using it.
515
516       ClientFlushed
517
518       "ClientFlushed" exposes POE::Wheel::ReadWrite's "FlushedEvent" as a
519       callback.  It is called whenever the client's output buffer has been
520       fully flushed to the client socket.  At this point it's safe to shut
521       down the socket without losing data.
522
523       "ClientFlushed" is useful for streaming servers, where a "flushed"
524       event signals the need to send more data.
525
526         ClientFlushed => sub {
527           my $data_source = $_[HEAP]{file_handle};
528           my $read_count = sysread($data_source, my $buffer = "", 65536);
529           if ($read_count) {
530             $_[HEAP]{client}->put($buffer);
531           }
532           else {
533             $_[KERNEL]->yield("shutdown");
534           }
535         },
536
537       POE::Component::Server::TCP's default "Acceptor" ensures that data is
538       flushed before finishing a client shutdown.
539
540       ClientInput
541
542       "ClientInput" defines a per-connection callback to handle client input.
543       This callback receives its parameters directly from
544       POE::Wheel::ReadWrite's "InputEvent".  ARG0 contains the input record,
545       the format of which is defined by "ClientFilter" or
546       "ClientInputFilter".  ARG1 has the wheel's unique ID, and so on.
547       Please see POE:Wheel::ReadWrite for an in-depth description of
548       "InputEvent".
549
550       "ClientInput" and "Acceptor" are mutually exclusive.  Enabling one
551       prohibits the other.
552
553         ClientInput => sub {
554           my $input = $_[ARG0];
555           $_[HEAP]{wheel}->put("You said: $input");
556         },
557
558       ClientInputFilter
559
560       "ClientInputFilter" is used with "ClientOutputFilter" to specify
561       different protocols for input and output.  Both must be used together.
562       Both follow the same usage as "ClientFilter".  Overrides the filter set
563       by "ClientFilter".
564
565         ClientInputFilter  => [ "POE::Filter::Line", Literal => "\n" ],
566         ClientOutputFilter => 'POE::Filter::Stream',
567
568       ClientOutputFilter
569
570       "ClientOutputFilter" is used with "ClientInputFilter" to specify
571       different protocols for input and output.  Both must be used together.
572       Both follow the same usage as "ClientFilter".  Overrides the filter set
573       by "ClientFilter".
574
575         ClientInputFilter  => POE::Filter::Line->new(Literal => "\n"),
576         ClientOutputFilter => 'POE::Filter::Stream',
577
578       ClientShutdownOnError
579
580       "ClientShutdownOnError" tells the component whether client connections
581       should be shut down automatically if an error is detected.  It defaults
582       to "true".  Setting it to false (0, undef, "") turns off this feature.
583
584       The application is responsible for dealing with client errors if this
585       feature is disabled.  Not doing so may cause the component to emit a
586       constant stream of errors, eventually bogging down the application with
587       dead connections that spin out of control.
588
589       Yes, this is terrible.  You have been warned.
590
591       SessionParams
592
593       "SessionParams" specifies additional parameters that will be passed to
594       the "SessionType" constructor at creation time.  It must be an array
595       reference.
596
597         SessionParams => [ options => { debug => 1, trace => 1 } ],
598
599       Note: POE::Component::Server::TCP supplies its own POE::Session
600       constructor parameters.  Conflicts between them and "SessionParams" may
601       cause the component to behave erratically.  To avoid such problems,
602       please limit SessionParams to the "options" hash.  See POE::Session for
603       an known options.
604
605       We may enable other options later.  Please let us know if you need
606       something.
607
608       SessionType
609
610       "SessionType" specifies the POE::Session subclass that will be created
611       for each new client connection.  "POE::Session" is the default.
612
613         SessionType => "POE::Session::MultiDispatch"
614

EVENTS

616       It's possible to manipulate a TCP server component by sending it
617       messages.
618
619   Main Server Commands
620       These events must be sent to the main server, usually by the alias set
621       in its Alias parameter.
622
623       disconnected
624
625       The "disconnected" event informs the TCP server that a connection was
626       closed.  It is needed when using "Concurrency" with an "Acceptor"
627       callback.  The custom Acceptor must provide its own disconnect
628       notification so that the server's connection counting logic works.
629
630       Otherwise Concurrency clients will be accepted, and then no more.  The
631       server will never know when clients have disconnected.
632
633       set_concurrency
634
635       "set_concurrency" set the number of simultaneous connections the server
636       will be willing to accept.  See "Concurrency" for more details.
637       "set_concurrency" must have one parameter: the new maximum connection
638       count.
639
640         $kernel->call("my_server_alias", "set_concurrency", $max_count);
641
642       shutdown
643
644       The "shutdown" event starts a graceful server shutdown.  No new
645       connections will be accepted.  Existing connections will be allowed to
646       finish.  The server will be destroyed after the last connection ends.
647
648   Per-Connection Commands
649       These commands affect each client connection session.
650
651       shutdown
652
653       Sending "shutdown" to an individual client session instructs the server
654       to gracefully shut down that connection.  No new input will be
655       received, and any buffered output will be sent before the session ends.
656
657       Client sessions usually yield("shutdown") when they wish to disconnect
658       the client.
659
660         ClientInput => sub {
661           if ($_[ARG0] eq "quit") {
662             $_[HEAP]{client}->put("B'bye!");
663             $_[KERNEL]->yield("shutdown");
664             return;
665           }
666
667           # Handle other input here.
668         },
669

Reserved HEAP Members

671       Unlike most POE modules, POE::Component::Server::TCP stores data in the
672       client sessions' HEAPs.  These values are provided as conveniences for
673       application developers.
674
675   HEAP Members for Master Listening Sessions
676       The master listening session holds different data than client
677       connections.
678
679       alias
680
681       $_[HEAP]{alias} contains the server's Alias.
682
683       concurrency
684
685       $_[HEAP]{concurrency} remembers the server's "Concurrency" parameter.
686
687       connections
688
689       $_[HEAP]{connections} is used to track the current number of concurrent
690       client connections.  It's incremented whenever a new connection is
691       accepted, and it's decremented whenever a client disconnects.
692
693       listener
694
695       $_[HEAP]{listener} contains the POE::Wheel::SocketFactory object used
696       to listen for connections and accept them.
697
698   HEAP Members for Connection Sessions
699       These data members exist within the individual connections' sessions.
700
701       client
702
703       $_[HEAP]{client} contains a POE::Wheel::ReadWrite object used to
704       interact with the client.  All POE::Wheel::ReadWrite methods work.
705
706       got_an_error
707
708       $_[HEAP]{got_an_error} remembers whether the client connection has
709       already encountered an error.  It is part of the shutdown-on-error
710       procedure.
711
712       remote_ip
713
714       $_[HEAP]{remote_ip} contains the remote client's numeric address in
715       human-readable form.
716
717       remote_port
718
719       $_[HEAP]{remote_port} contains the remote client's numeric socket port
720       in human-readable form.
721
722       remote_addr
723
724       $_[HEAP]{remote_addr} contains the remote client's packed socket
725       address in computer-readable form.
726
727       shutdown
728
729       $_[HEAP]{shutdown} is true if the client is in the process of shutting
730       down.  The component uses it to ignore client input during shutdown,
731       and to close the connection after pending output has been flushed.
732
733       shutdown_on_error
734
735       $_[HEAP]{shutdown_on_error} remembers whether the client connection
736       should automatically shut down if an error occurs.
737

SEE ALSO

739       The SEE ALSO section in POE contains a table of contents covering the
740       entire POE distribution.
741
742       POE::Component::Client::TCP is the client-side counterpart to this
743       module.
744
745       This component uses and exposes features from POE::Filter,
746       POE::Wheel::SocketFactory, and POE::Wheel::ReadWrite.
747

BUGS

749       This looks nothing like what Ann envisioned.
750
751       This component currently does not accept many of the options that
752       POE::Wheel::SocketFactory does.
753
754       This component will not bind to several addresses at once.  This may be
755       a limitation in SocketFactory, but it's not by design.
756
757       This component needs better error handling.
758
759       Some use cases require different session classes for the listener and
760       the connection handlers.  This isn't currently supported.  Please send
761       patches. :)
762

AUTHORS & COPYRIGHTS

764       POE::Component::Server::TCP is Copyright 2000-2013 by Rocco Caputo.
765       All rights are reserved.  POE::Component::Server::TCP is free software,
766       and it may be redistributed and/or modified under the same terms as
767       Perl itself.
768
769       POE::Component::Server::TCP is based on code, used with permission,
770       from Ann Barcomb <kudra@domaintje.com>.
771
772       POE::Component::Server::TCP is based on code, used with permission,
773       from Jos Boumans <kane@cpan.org>.
774
775
776
777perl v5.38.0                      2023-07-21    POE::Component::Server::TCP(3)
Impressum