POE::Component::Server::TCP - a simplified TCP server
use POE qw(Component::Server::TCP); # First form just accepts connections. POE::Component::Server::TCP->new ( Port => $bind_port, Address => $bind_address, # Optional. Domain => AF_INET, # Optional. Alias => $session_alias, # Optional. Acceptor => \&accept_handler, Error => \&error_handler, # Optional. ); # Second form accepts and handles connections. POE::Component::Server::TCP->new ( Port => $bind_port, Address => $bind_address, # Optional. Domain => AF_INET, # Optional. Alias => $session_alias, # Optional. Acceptor => \&accept_handler, # Optional. Error => \&error_handler, # Optional. Args => [ "arg0", "arg1" ], # Optional. SessionType => "POE::Session::Abc", # Optional. SessionParams => [ options => { debug => 1 } ], # Optional. ClientInput => \&handle_client_input, # Required. ClientConnected => \&handle_client_connect, # Optional. ClientDisconnected => \&handle_client_disconnect, # Optional. ClientError => \&handle_client_error, # Optional. ClientFlushed => \&handle_client_flush, # Optional. ClientFilter => "POE::Filter::Xyz", # Optional. ClientShutdownOnError => 0, # Optional. # Optionally define other states for the client session. InlineStates => { ... }, PackageStates => [ ... ], ObjectStates => [ ... ], ); # Call signatures for handlers. sub accept_handler { my ($socket, $remote_address, $remote_port) = @_[ARG0, ARG1, ARG2]; } sub error_handler { my ($syscall_name, $error_number, $error_string) = @_[ARG0, ARG1, ARG2]; } sub handle_client_input { my $input_record = $_[ARG0]; } sub handle_client_error { my ($syscall_name, $error_number, $error_string) = @_[ARG0, ARG1, ARG2]; } sub handle_client_connect { # no special parameters } sub handle_client_disconnect { # no special parameters } sub handle_client_flush { # no special parameters } # Reserved HEAP variables: $heap->{listener} = SocketFactory (only Acceptor and Error callbacks) $heap->{client} = ReadWrite (only in ClientXyz callbacks) $heap->{remote_ip} = remote IP address in dotted form $heap->{remote_port} = remote port $heap->{remote_addr} = packed remote address and port $heap->{shutdown} = shutdown flag (check to see if shutting down) $heap->{shutdown_on_error} = Automatically disconnect on error. # Accepted public events. $kernel->yield( "shutdown" ) # initiate shutdown in a connection $kernel->post( server => "shutdown" ) # stop listening for connections # Responding to a client. $heap->{client}->put(@things_to_send);
The TCP server component hides the steps needed to create a server using Wheel::SocketFactory. The steps aren't many, but they're still tiresome after a while.
POE::Component::Server::TCP supplies common defaults for most callbacks and handlers. The authors hope that servers can be created with as little work as possible.
Constructor parameters:
Acceptor is a coderef which will be called to handle accepted sockets. The coderef receives its parameters directly from SocketFactory's SuccessEvent. ARG0 is the accepted socket handle, suitable for giving to a ReadWrite wheel. ARG1 and ARG2 contain the packed remote address and numeric port, respectively. ARG3 is the SocketFactory wheel's ID.
Acceptor => \&accept_handler
Acceptor lets programmers rewrite the guts of Server::TCP entirely. It disables the code that provides the /Client.*/ callbacks.
Address is the optional interface address the TCP server will bind to. It defaults to INADDR_ANY or INADDR6_ANY when using IPv4 or IPv6, respectively.
Address => '127.0.0.1' # Localhost IPv4 Address => "::1" # Localhost IPv6
It's passed directly to SocketFactory's BindAddress parameter, so it can be in whatever form SocketFactory supports. At the time of this writing, that's a dotted quad, an IPv6 address, a host name, or a packed Internet address.
Alias is an optional name by which this server may be referenced. It's used to pass events to a TCP server from other sessions.
Alias => 'chargen'
Later on, the 'chargen' service can be shut down with:
$kernel->post( chargen => 'shutdown' );
SessionType specifies what type of sessions will be created within the TCP server. It must be a scalar value.
SessionType => "POE::Session::MultiDispatch"
SessionType is optional. The component will supply a "POE::Session" type if none is specified.
Initialize parameters to be passed to the SessionType when it is created. This must be an array reference.
SessionParams => [ options => { debug => 1, trace => 1 } ],
It is important to realize that some of the arguments to SessionHandler may get clobbered when defining them for your SessionHandler. It is advised that you stick to defining arguments in the "options" hash such as trace and debug. See POE::Session for an example list of options.
ClientConnected is a coderef that will be called for each new client connection. ClientConnected callbacks receive the usual POE parameters, but nothing special is included.
ClientDisconnected is a coderef that will be called for each client that disconnects. ClientDisconnected callbacks receive the usual POE parameters, but nothing special is included.
ClientError is a coderef that will be called whenever an error occurs on a socket. It receives the usual error handler parameters: ARG0 is the name of the function that failed. ARG1 is the numeric failure code ($! in numeric context). ARG2 is the string failure code ($! in string context).
If ClientError is omitted, a default one will be provided. The default error handler logs the error to STDERR and closes the connection.
ClientFilter specifies the type of filter that will parse input from each client. It may either be a scalar or a list reference. If it is a scalar, it will contain a POE::Filter class name. If it is a list reference, the first item in the list will be a POE::Filter class name, and the remaining items will be constructor parameters for the filter. For example, this changes the line separator to a vertical bar:
ClientFilter => [ "POE::Filter::Line", InputLiteral => "|" ],
ClientFilter is optional. The component will supply a "POE::Filter::Line" instance if none is specified. If you supply a different value for Filter, then you must also use that filter class.
use
ClientInput is a coderef that will be called to handle client input. The callback receives its parameters directly from ReadWrite's InputEvent. ARG0 is the input record, and ARG1 is the wheel's unique ID.
ClientInput => \&input_handler
ClientInput and Acceptor are mutually exclusive. Enabling one prohibits the other.
ClientShutdownOnError is a boolean value that determines whether client sessions shut down automatically on errors. The default value is 1 (true). Setting it to 0 or undef (false) turns this off.
If client shutdown-on-error is turned off, it becomes your responsibility to deal with client errors properly. Not handling them, or not closing wheels when they should be, will cause the component to spit out a constant stream of errors, eventually bogging down your application with dead connections that spin out of control.
Specifies the domain within which communication will take place. It selects the protocol family which should be used. Currently supported values are AF_INET, AF_INET6, PF_INET or PF_INET6. This parameter is optional and will default to AF_INET if omitted.
Note: AF_INET6 and PF_INET6 are supplied by the Socket6 module, which is available on the CPAN. You must have Socket6 loaded before POE::Component::Server::TCP will create IPv6 sockets.
Error is an optional coderef which will be called to handle server socket errors. The coderef is used as POE::Wheel::SocketFactory's FailureEvent, so it accepts the same parameters. If it is omitted, a default error handler will be provided. The default handler will log the error to STDERR and shut down the server.
InlineStates holds a hashref of inline coderefs to handle events. The hashref is keyed on event name. For more information, see POE::Session's create() method.
ObjectStates holds a list reference of objects and the events they handle. For more information, see POE::Session's create() method.
PackageStates holds a list reference of Perl package names and the events they handle. For more information, see POE::Session's create() method.
Args passes the contents of a LISTREF to the ClientConnected callback via @_[ARG0..$#_]. It allows you to pass extra information to the session created to handle the client connection.
Port is the port the listening socket will be bound to. It defaults to INADDR_ANY, which usually lets the operating system pick a port.
Port => 30023
It's possible to manipulate a TCP server component from some other session. This is useful for shutting them down, and little else so far.
Shuts down the TCP server. This entails destroying the SocketFactory that's listening for connections and removing the TCP server's alias, if one is set.
POE::Component::Client::TCP, POE::Wheel::SocketFactory, POE::Wheel::ReadWrite, POE::Filter
This is not suitable for complex tasks. For example, you cannot engage in a challenge-response with the client-- you can only reply to the one message a client sends.
This looks nothing like what Ann envisioned.
This component currently does not accept many of the options that POE::Wheel::SocketFactory does.
This component will not bind to several addresses. This may be a limitation in SocketFactory.
This component needs more complex error handling which appends for construction errors and replaces for runtime errors, instead of replacing for all.
POE::Component::Server::TCP is Copyright 2000-2001 by Rocco Caputo. All rights are reserved. POE::Component::Server::TCP is free software, and it may be redistributed and/or modified under the same terms as Perl itself.
POE::Component::Server::TCP is based on code, used with permission, from Ann Barcomb <kudra@domaintje.com>.
POE::Component::Server::TCP is based on code, used with permission, from Jos Boumans <kane@cpan.org>.
To install POE::Component::Server::TCP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::Server::TCP
CPAN shell
perl -MCPAN -e shell install POE::Component::Server::TCP
For more information on module installation, please visit the detailed CPAN module installation guide.