NAME
Net::Waiter compact INET socket serverSYNOPSIS
package MyWaiter;
use strict;
use parent qw( Net::Waiter );
sub on_accept_ok
{
my $self = shift;
my $sock = shift;
my $peerhost = $sock->peerhost();
print "client connected from $peerhost\n";
}
sub on_process
{
my $self = shift;
my $sock = shift;
print $sock "hello world\n";
}
#--------------------------------------------------
packgage main;
use strict;
use MyWaiter;
my $server = MyWaiter->new( PORT => 9123 );
my $res = $server->run();
print "waiter result: $res\n"; # 0 is ok, >0 is errorDESCRIPTION
Net::Waiter is a base class which implements compact INET network socket server.
METHODS/FUNCTIONS
new( OPTION => VALUE, ... )
Creates new Net::Waiter object and sets its options:
PORT => 9123, # which port to listen on
PREFORK => 8, # how many preforked processes
MAXFORK => 32, # max count of preforked processes
NOFORK => 0, # if 1 will not fork, only single client will be accepted
TIMEOUT => 4, # timeout for accepting connections, defaults to 4 seconds
SSL => 1, # use SSL
PX_IDLE => 31, # prefork exit idle time, defaults to 31
PROP_SIGUSR => 1, # if true, will propagate USR1/USR2 signals to childs
DEBUG => 1, # enable debug mode, prints debug messagesif PREFORK is negative, the absolute value will be used both for PREFORK and MAXFORK counts.
if SSL is enabled then additional IO::Socket::SSL options can be added:
SSL_cert_file => 'cert.pem',
SSL_key_file => 'key.pem',
SSL_ca_file => 'ca.pem',for further details, check IO::Socket::SSL docs.
run()
This executes server main loop. It will create new server socket, set options (listen port, ssl options, etc.) then fork and call handlers along the way.
Run returns exit code:
0 -- ok
100 -- cannot create server listen socketbreak_main_loop()
Breaks main server loop. Calling break_main_loop() is possible from parent server process handler functions (see HANDLER FUNCTIONS below) but it will not break the main loop immediately. It will just rise flag which will stop when control is returned to the next server loop.
ssl_in_use()
Returns true (1) if current setup uses SSL (useful mostly inside handlers).
is_child()
Returns true (1) if this process is client/child process (useful mostly inside handlers).
get_server_socket()
Returns server (listening) socket object. Valid in parent only, otherwise returns undef.
get_client_socket()
Returns connected client socket.
get_busy_kids_count()
Returns the count of all forked busy processes (which are already accepted connection). In array contect returns two integers: busy process count and all forked processes count. This method is accessible from parent and all forked processes and reflect all processes.
Returns client (connected) socket object. Valid in kids only, otherwise returns undef.
get_kid_pids()
Returns list of forked child pids. Available only in parent processes.
propagate_signal( 'SIGNAME' )
Sends signal 'SIGNAME' to all child processes.
HANDLER FUNCTIONS
All of the following methods are empty in the base implementation and are expected to be reimplemented. The list order below is chronological but the most important function which must be reimplemented is on_process().
on_listen_ok()
Called when listen socket is ready but no connection is accepted yet.
on_accept_error()
Called if there is an error with accepting connections.
on_accept_ok( $client_socket )
Called when new connection is accepted without error.
on_fork_ok( $child_pid )
Called when new process is forked. This will be executed inside the server (parent) process and will have forked (child) process pid as 1st argument.
on_process( $client_socket )
Called when socket is ready to be used. This is the place where the actual work must be done.
on_prefork_child_idle
Called on preforked childs, when accept timeouts (see 'TIMEOUT' option).
on_forking_idle
Called on forking mode parent, when accept timeouts (see 'TIMEOUT' option).
on_maxforked( $client_socket )
Called if client socket is accepted but MAXFORK count reached. This can be used to advise the situation over the socket and will be called right before client socket close.
note: this handler is only used for FORKING server. preforked servers will not accept the socket at all if MAXFORK has been reached. the reason is that forking server may release child process during the accept() call.
on_child_start()
Called right after fork, in the forked child, after initial setup but just before processing start.
on_child_exit()
Called inside a child, just before forked or preforked child exits.
on_close( $client_socket )
Called right before client socket will be closed. And after on_process(). Will be called and when MAXFORK has been reached also.
on_server_close()
Called right before server (listen) socket is closed (i.e. when main loop is interrupted). This is the last handler to be called on each run().
on_ssl_error( $ssl_handshake_error )
Called when SSL handshake or other error encountered. Gets error message as 1st argument.
on_sig_child( $child_pid )
Called when child/client process finishes. It executes only inside the parent/server process and gets child pid as 1st argument.
on_sig_usr1()
Called when server process receives USR1 signal.
on_sig_usr2()
Called when server process receives USR2 signal.
on_child_sig_usr1()
Called when forked (child) process receives USR1 signal.
on_child_sig_usr2()
Called when forked (child) process receives USR2 signal.
log() and log_debug()
Called when Waiter prints (debug) messages. Should be reimplemented to use specific log facility. By default it prints messages to STDERR. Can be reimplemented empty to supress any messages.
NOTES
SIG_CHLD handler defaults to IGNORE in child processes. whoever forks further here, should reinstall signal handler if needed.
TODO
(more docs)REQUIRED MODULES
Net::Waiter tries to use as little modules as possible. Currenlty only those core modules are in use: * IO::Socket::INET * POSIX ":sys_wait_h"; * IO::Socket::INET; * Sys::SigAction qw( set_sig_handler ); * IPC::Shareable; * Data::Dumper;
DEMO
For demo server check 'demo' directory in the source tar package or at the GITHUB repository:
https://github.com/cade-vs/perl-net-waiter/tree/master/demo GITHUB REPOSITORY
https://github.com/cade-vs/perl-net-waiter
git@github.com:cade-vs/perl-net-waiter.git
git clone git://github.com/cade-vs/perl-net-waiter.gitAUTHOR
Vladi Belperchinov-Shabanski "Cade"
<cade@biscom.net> <cade@cpan.org> <cade@datamax.bg>
http://cade.datamax.bg