NAME¶
Net::Server::Multiplex - Multiplex several connections within one process
SYNOPSIS¶
package MyPlexer;
use base qw(Net::Server::Multiplex);
sub mux_input {
#...code...
}
__PACKAGE__->run();
DESCRIPTION¶
This personality is designed to handle multiple connections all within one
process. It should only be used with protocols that are guaranteed to be able
to respond quickly on a packet by packet basis. If determining a response
could take a while or an unknown period of time, all other connections
established will block until the response completes. If this condition might
ever occur, this personality should probably not be used.
This takes some nice features of Net::Server (like the server listen socket
setup, configuration file processing, safe signal handling, convenient inet
style STDIN/STDOUT handling, logging features, deamonization and pid tracking,
and restartability -SIGHUP) and some nice features of IO::Multiplex (automatic
buffered IO and per-file-handle objects) and combines them for an easy-to-use
interace.
See examples/samplechat.pl distributed with Net::Server for a simple chat server
that uses several of these features.
PROCESS FLOW¶
The process flow is written in an open, easy to override, easy to hook, fashion.
The basic flow is shown below.
$self->configure_hook;
$self->configure(@_);
$self->post_configure;
$self->post_configure_hook;
$self->pre_bind;
$self->bind;
if (Restarting server) {
$self->restart_open_hook();
}
$self->post_bind_hook;
$self->post_bind;
$self->pre_loop_hook;
$self->loop; # This basically just runs IO::Multiplex::loop
# For routines inside a $self->loop
# See CLIENT PROCESSING below
$self->pre_server_close_hook;
$self->post_child_cleanup_hook;
$self->server_close;
if (Restarting server) {
$self->restart_close_hook();
$self->hup_server;
# Redo process again starting with configure_hook
}
The server then exits.
CLIENT PROCESSING¶
The following represents the client processing program flow:
$self->{server}->{client} = Net::Server::Proto::TCP->accept(); # NOTE: Multiplexed with mux_input() below
if (check_for_dequeue seconds have passed) {
$self->run_dequeue();
}
$self->get_client_info;
$self->post_accept_hook; # Net::Server style
if ($self->allow_deny
&& $self->allow_deny_hook) {
# (Net::Server style $self->process_request() is never called.)
# A unique client specific object is created
# for all mux_* methods from this point on.
$self = __PACKAGE__->new($self, client);
$self->mux_connection; # IO::Multiplex style
for (every packet received) {
$self->mux_input; # NOTE: Multiplexed with accept() above
}
} else {
$self->request_denied_hook;
# Notice that if either allow_deny or allow_deny_hook fails, then
# new(), mux_connection(), and mux_input() will never be called.
# mux_eof() and mux_close() will still be called, but using a
# common listen socket callback object instead of a unique client
# specific object.
}
$self->mux_eof;
$self->post_process_request_hook;
$self->mux_close;
This process then loops multiplexing between the
accept() for the next
connection and
mux_input() when input arrives to avoid blocking either
one.
HOOKS¶
The *_hook methods mentioned above are meant to be overridden with your own
subroutines if you desire to provide additional functionality.
The
loop() method of Net::Server has been overridden to run the loop
routine of IO::Multiplex instead. The Net::Server methods may access the
IO::Multiplex object at "$self->{mux}" if desired. The
IO::Multiplex methods may access the Net::Server object at
"$self->{net_server}" if desired.
The
process_request() method is never used with this personality.
The other Net::Server hooks and methods should work the same.
- "$self->run_dequeue()"
- This hook only gets called in conjunction with the check_for_dequeue
setting. It will run every check_for_dequeue seconds. Since no forking is
done, this hook should run fast in order to prevent blocking the rest of
the processing.
TIMEOUTS¶
set_timeout¶
To utilize the optional timeout feature of IO::Multiplex, you need to specify a
timeout by using the set_timeout method.
$self->{net_server}->{mux}->set_timeout($fh, $seconds_from_now);
$fh may be either a client socket or a listen socket file descriptor within the
mux. $seconds_from_now may be fractional to achieve more precise timeouts.
This is used in conjunction with mux_timeout, which you should define
yourself.
mux_timeout¶
The main
loop() routine will call $obj->mux_timeout($mux, $fh) when
the timeout specified in set_timeout is reached where $fh is the same as the
one specified in
set_timeout() and $obj is its corresponding object
(either the unique client specific object or the main listen callback object)
and $mux is the main IO::Multiplex object itself.
CALLBACK INTERFACE¶
Callback objects should support the following interface. You do not have to
provide all of these methods, just provide the ones you are interested in.
These are just like the IO::Multiplex hooks except that STDOUT is tied to the
corresponding client socket handle for your convenience and to more closely
emulate the Net::Server model. However, unlike some other Net::Server
personalities, you should never read directly from STDIN yourself. You should
define one or more of the following methods:
mux_connection ($mux,$fh)¶
(OPTIONAL) Run once when the client first connects if the allow_deny passes.
Note that the "$self->{net_server}->{server}" property hash
may be modified by future connections through Net::Server. Any values within
it that this object may need to use later should be copied within its own
object at this point.
Example:
$self->{peerport} = $self->{net_server}->{server}->{peerport};
(REQUIRED) Run each time a packet is read. It should consume $data starting at
the left and leave unconsumed data in the scalar for future calls to
mux_input.
mux_eof ($mux,$fh,\$data)¶
(OPTIONAL) Run once when the client is done writing. It should consume the rest
of $data since
mux_input() will never be run again.
mux_close ($mux,$fh)¶
(OPTIONAL) Run after the entire client socket has been closed. No more attempts
should be made to read or write to the client or to STDOUT.
mux_timeout ($mux,$fh)¶
(OPTIONAL) Run once when the set_timeout setting expires as explained above.
BUGS¶
This is only known to work with TCP servers.
If you need to use the IO::Multiplex style set_timeout / mux_timeout interface,
you cannot use the Net::Server style check_for_dequeue / run_dequeue
interface. It will not work if the check_for_dequeue option is specified. The
run_dequeue method is just a compatibility interface to comply with the
Net::Server::Fork style run_dequeue but is implemented in terms of the
IO::Multiplex style set_timeout and mux_timeout methods.
AUTHOR¶
Rob Brown <bbb@cpan.org>
MAINTAINER¶
Paul Seamons <paul@seamons.com>
LICENSE¶
This package may be distributed under the terms of either the
GNU General Public License
or the
Perl Artistic License
All rights reserved.
SEE ALSO¶
Net::Server by Paul Seamons <paul@seamons.com>,
IO::Multiplex by Bruce Keeler <bruce@gridpoint.com>.