NAME
Net::Server::Multiplex - Multiplex several connections within one
process
SYNOPSIS
package MyPlexer;
use base 'Net::Server::Multiplex';
sub muxinput {
#...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.
PPRROOCCEESSSS FFLLOOWW
The process flow is written in an open, easy to override, easy to hook,
fashion. The basic flow is shown below.
$self->configurehook;
$self->configure(@);
$self->postconfigure;
$self->postconfigurehook;
$self->prebind;
$self->bind;
if( Restarting server ){
$self->restartopenhook();
}
$self->postbindhook;
$self->postbind;
$self->preloophook;
$self->loop; # This basically just runs IO::Multiplex::loop
# For routines inside a $self->loop
# See CLIENT PROCESSING below
$self->preserverclosehook;
$self->postchildcleanuphook;
$self->serverclose;
if( Restarting server ){
$self->restartclosehook();
$self->hupserver;
# Redo process again starting with configurehook
}
The server then exits.
CCLLIIEENNTT PPRROOCCEESSSSIINNGG
The following represents the client processing program flow:
$self->{server}->{client} = Net::Server::Proto::TCP->accept(); # NOTE: Multiplexed with muxinput() below
if (checkfordequeue seconds have passed) {
$self->rundequeue();
}
$self->getclientinfo;
$self->postaccepthook; # Net::Server style
if( $self->allowdeny
&& $self->allowdenyhook ){
# (Net::Server style $self->processrequest() is never called.)
# A unique client specific object is created
# for all mux* methods from this point on.
$self = PACKAGE->new($self, client);
$self->muxconnection; # IO::Multiplex style
for (every packet received) {
$self->muxinput; # NOTE: Multiplexed with accept() above
}
}else{
$self->requestdeniedhook;
# Notice that if either allowdeny or allowdenyhook fails, then
# new(), muxconnection(), and muxinput() will never be called.
# muxeof() and muxclose() will still be called, but using a
# common listen socket callback object instead of a unique client
# specific object.
}
$self->muxeof;
$self->postprocessrequesthook;
$self->muxclose;
This process then loops multiplexing between the accept() for the next
connection and muxinput() when input arrives to avoid blocking either
one.
HHOOOOKKSS
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->{netserver}" if desired.
The processrequest() method is never used with this personality.
The other Net::Server hooks and methods should work the same.
"$self->rundequeue()"
This hook only gets called in conjuction with the checkfordequeue
setting. It will run every checkfordequeue seconds. Since no
forking is done, this hook should run fast in order to prevent
blocking the rest of the processing.
TTIIMMEEOOUUTTSS
sseettttiimmeeoouutt
To utilize the optional timeout feature of IO::Multiplex, you need to
specify a timeout by using the settimeout method.
$self->{netserver}->{mux}->settimeout($fh, $secondsfromnow);
$fh may be either a client socket or a listen socket file descriptor
within the mux. $secondsfromnow may be fractional to achieve more
precise timeouts. This is used in conjuction with muxtimeout, which
you should define yourself.
mmuuxxttiimmeeoouutt
The main loop() routine will call $obj->muxtimeout($mux, $fh) when the
timeout specified in settimeout is reached where $fh is the same as
the one specified in settimeout() 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.
CCAALLLLBBAACCKK IINNTTEERRFFAACCEE
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:
mmuuxxccoonnnneeccttiioonn (($$mmuuxx,,$$ffhh))
(OPTIONAL) Run once when the client first connects if the allowdeny
passes. Note that the "$self->{netserver}->{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->{netserver}->{server}->{peerport};
mmuuxxiinnppuutt (($$mmuuxx,,$$ffhh,,\\$$ddaattaa))
(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 muxinput.
mmuuxxeeooff (($$mmuuxx,,$$ffhh,,\\$$ddaattaa))
(OPTIONAL) Run once when the client is done writing. It should consume
the rest of $data since muxinput() will never be run again.
mmuuxxcclloossee (($$mmuuxx,,$$ffhh))
(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.
mmuuxxttiimmeeoouutt (($$mmuuxx,,$$ffhh))
(OPTIONAL) Run once when the settimeout setting expires as explained
above.
BUGS
This is only known to work with TCP servers.
If you need to use the IO::Multiplex style settimeout / muxtimeout
interface, you cannot use the Net::Server style checkfordequeue /
rundequeue interface. It will not work if the checkfordequeue
option is specified. The rundequeue method is just a compatibility
interface to comply with the Net::Server::Fork style rundequeue but is
implemented in terms of the IO::Multiplex style settimeout and
muxtimeout methods.
Please notify me, the author, of any other problems or issues you find.
AUTHOR Copyright (C) 2001-2003, Rob Brown
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 ,
IO::Multiplex by Bruce Keeler .
perl v5.8.8 2003-11-06 Net::Server::Multiplex(3)