.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::Server::Multiplex 3"
.TH Net::Server::Multiplex 3 "2007-02-02" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Net::Server::Multiplex \- Multiplex several connections within one process
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package MyPlexer;
.Ve
.PP
.Vb 1
\&  use base 'Net::Server::Multiplex';
.Ve
.PP
.Vb 3
\&  sub mux_input {
\&     #...code...
\&  }
.Ve
.PP
.Vb 1
\&  __PACKAGE__->run();
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
This takes some nice features of Net::Server (like the server
listen socket setup, configuration file processing, safe signal
handling, convenient inet style \s-1STDIN/STDOUT\s0 handling, logging
features, deamonization and pid tracking, and restartability
\&\-SIGHUP) and some nice features of IO::Multiplex (automatic
buffered \s-1IO\s0 and per-file-handle objects) and combines them for
an easy-to-use interace.
.PP
See examples/samplechat.pl distributed with Net::Server for a
simple chat server that uses several of these features.
.SH "PROCESS FLOW"
.IX Header "PROCESS FLOW"
The process flow is written in an open, easy to
override, easy to hook, fashion.  The basic flow is
shown below.
.PP
.Vb 1
\&  $self->configure_hook;
.Ve
.PP
.Vb 1
\&  $self->configure(@_);
.Ve
.PP
.Vb 1
\&  $self->post_configure;
.Ve
.PP
.Vb 1
\&  $self->post_configure_hook;
.Ve
.PP
.Vb 1
\&  $self->pre_bind;
.Ve
.PP
.Vb 1
\&  $self->bind;
.Ve
.PP
.Vb 3
\&  if( Restarting server ){
\&     $self->restart_open_hook();
\&  }
.Ve
.PP
.Vb 1
\&  $self->post_bind_hook;
.Ve
.PP
.Vb 1
\&  $self->post_bind;
.Ve
.PP
.Vb 1
\&  $self->pre_loop_hook;
.Ve
.PP
.Vb 3
\&  $self->loop; # This basically just runs IO::Multiplex::loop
\&  # For routines inside a $self->loop
\&  # See CLIENT PROCESSING below
.Ve
.PP
.Vb 1
\&  $self->pre_server_close_hook;
.Ve
.PP
.Vb 1
\&  $self->post_child_cleanup_hook;
.Ve
.PP
.Vb 1
\&  $self->server_close;
.Ve
.PP
.Vb 5
\&  if( Restarting server ){
\&     $self->restart_close_hook();
\&     $self->hup_server;
\&     # Redo process again starting with configure_hook
\&  }
.Ve
.PP
The server then exits.
.SH "CLIENT PROCESSING"
.IX Header "CLIENT PROCESSING"
The following represents the client processing program flow:
.PP
.Vb 1
\&  $self->{server}->{client} = Net::Server::Proto::TCP->accept();  # NOTE: Multiplexed with mux_input() below
.Ve
.PP
.Vb 3
\&  if (check_for_dequeue seconds have passed) {
\&    $self->run_dequeue();
\&  }
.Ve
.PP
.Vb 1
\&  $self->get_client_info;
.Ve
.PP
.Vb 1
\&  $self->post_accept_hook; # Net::Server style
.Ve
.PP
.Vb 1
\&  if( $self->allow_deny
.Ve
.PP
.Vb 1
\&      && $self->allow_deny_hook ){
.Ve
.PP
.Vb 1
\&    # (Net::Server style $self->process_request() is never called.)
.Ve
.PP
.Vb 3
\&    # A unique client specific object is created
\&    # for all mux_* methods from this point on.
\&    $self = __PACKAGE__->new($self, client);
.Ve
.PP
.Vb 1
\&    $self->mux_connection; # IO::Multiplex style
.Ve
.PP
.Vb 3
\&    for (every packet received) {
\&      $self->mux_input;  # NOTE: Multiplexed with accept() above
\&    }
.Ve
.PP
.Vb 1
\&  }else{
.Ve
.PP
.Vb 1
\&    $self->request_denied_hook;
.Ve
.PP
.Vb 5
\&    # 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.
.Ve
.PP
.Vb 1
\&  }
.Ve
.PP
.Vb 1
\&  $self->mux_eof;
.Ve
.PP
.Vb 1
\&  $self->post_process_request_hook;
.Ve
.PP
.Vb 1
\&  $self->mux_close;
.Ve
.PP
This process then loops multiplexing between the \fIaccept()\fR
for the next connection and \fImux_input()\fR when input arrives
to avoid blocking either one.
.SH "HOOKS"
.IX Header "HOOKS"
The *_hook methods mentioned above are meant to be overridden
with your own subroutines if you desire to provide additional
functionality.
.PP
The \fIloop()\fR 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 \f(CW\*(C`$self\->{mux}\*(C'\fR if
desired.  The IO::Multiplex methods may access the Net::Server
object at \f(CW\*(C`$self\->{net_server}\*(C'\fR if desired.
.PP
The \fIprocess_request()\fR method is never used with this personality.
.PP
The other Net::Server hooks and methods should work the same.
.ie n .IP """$self\->run_dequeue()""" 4
.el .IP "\f(CW$self\->run_dequeue()\fR" 4
.IX Item "$self->run_dequeue()"
This hook only gets called in conjuction 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.
.SH "TIMEOUTS"
.IX Header "TIMEOUTS"
.Sh "set_timeout"
.IX Subsection "set_timeout"
To utilize the optional timeout feature of IO::Multiplex,
you need to specify a timeout by using the set_timeout
method.
.PP
$self\->{net_server}\->{mux}\->set_timeout($fh, \f(CW$seconds_from_now\fR);
.PP
$fh may be either a client socket or a listen socket file descriptor
within the mux.  \f(CW$seconds_from_now\fR may be fractional to achieve
more precise timeouts.  This is used in conjuction with mux_timeout,
which you should define yourself.
.Sh "mux_timeout"
.IX Subsection "mux_timeout"
The main \fIloop()\fR routine will call \f(CW$obj\fR\->mux_timeout($mux, \f(CW$fh\fR)
when the timeout specified in set_timeout is reached where
\&\f(CW$fh\fR is the same as the one specified in \fIset_timeout()\fR and
\&\f(CW$obj\fR is its corresponding object (either the unique client
specific object or the main listen callback object) and
\&\f(CW$mux\fR is the main IO::Multiplex object itself.
.SH "CALLBACK INTERFACE"
.IX Header "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 \s-1STDOUT\s0 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 \s-1STDIN\s0
yourself.   You should define one or more of the following methods:
.Sh "mux_connection ($mux,$fh)"
.IX Subsection "mux_connection ($mux,$fh)"
(\s-1OPTIONAL\s0)
Run once when the client first connects if the allow_deny passes.
Note that the \f(CW\*(C`$self\->{net_server}\->{server}\*(C'\fR 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.
.PP
Example:
  \f(CW$self\fR\->{peerport} = \f(CW$self\fR\->{net_server}\->{server}\->{peerport};
.Sh "mux_input ($mux,$fh,\e$data)"
.IX Subsection "mux_input ($mux,$fh,$data)"
(\s-1REQUIRED\s0)
Run each time a packet is read.  It should consume \f(CW$data\fR starting
at the left and leave unconsumed data in the scalar for future
calls to mux_input.
.Sh "mux_eof ($mux,$fh,\e$data)"
.IX Subsection "mux_eof ($mux,$fh,$data)"
(\s-1OPTIONAL\s0)
Run once when the client is done writing.  It should consume
the rest of \f(CW$data\fR since \fImux_input()\fR will never be run again.
.Sh "mux_close ($mux,$fh)"
.IX Subsection "mux_close ($mux,$fh)"
(\s-1OPTIONAL\s0)
Run after the entire client socket has been closed.  No more
attempts should be made to read or write to the client or to
\&\s-1STDOUT\s0.
.Sh "mux_timeout ($mux,$fh)"
.IX Subsection "mux_timeout ($mux,$fh)"
(\s-1OPTIONAL\s0)
Run once when the set_timeout setting expires as
explained above.
.SH "BUGS"
.IX Header "BUGS"
This is only known to work with \s-1TCP\s0 servers.
.PP
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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Rob Brown <bbb@cpan.org>
.SH "MAINTAINER"
.IX Header "MAINTAINER"
Paul Seamons <paul@seamons.com>
.SH "LICENSE"
.IX Header "LICENSE"
.Vb 4
\&  This package may be distributed under the terms of either the
\&  GNU General Public License
\&     or the
\&  Perl Artistic License
.Ve
.PP
.Vb 1
\&  All rights reserved.
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::Server by Paul Seamons <paul@seamons.com>,
.PP
IO::Multiplex by Bruce Keeler <bruce@gridpoint.com>.