.\" 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::PreForkSimple 3"
.TH Net::Server::PreForkSimple 3 "2007-03-26" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Net::Server::PreForkSimple \- Net::Server personality
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Net::Server::PreForkSimple;
\&  @ISA = qw(Net::Server::PreForkSimple);
.Ve
.PP
.Vb 3
\&  sub process_request {
\&     #...code...
\&  }
.Ve
.PP
.Vb 1
\&  __PACKAGE__->run();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Please read the pod on Net::Server first.  This module
is a personality, or extension, or sub class, of the
Net::Server module.
.PP
This personality binds to one or more ports and then forks
\&\f(CW\*(C`max_servers\*(C'\fR child processes.  The server will make sure
that at any given time there are always \f(CW\*(C`max_servers\*(C'\fR
available to receive a client request.  Each of
these children will process up to \f(CW\*(C`max_requests\*(C'\fR client
connections.  This type is good for a heavily hit site that can
keep \f(CW\*(C`max_servers\*(C'\fR processes dedicated to the serving.
(Multi port accept defaults to using flock to serialize the
children).
.PP
At this time, it does not appear that this module will pass tests on
Win32 systems.  Any ideas or patches for making the tests pass would be
welcome.
.SH "SAMPLE CODE"
.IX Header "SAMPLE CODE"
Please see the sample listed in Net::Server.
.SH "COMMAND LINE ARGUMENTS"
.IX Header "COMMAND LINE ARGUMENTS"
In addition to the command line arguments of the Net::Server
base class, Net::Server::PreFork contains several other
configurable parameters.
.PP
.Vb 3
\&  Key               Value                   Default
\&  max_servers       \ed+                     50
\&  max_requests      \ed+                     1000
.Ve
.PP
.Vb 3
\&  serialize         (flock|semaphore|pipe)  undef
\&  # serialize defaults to flock on multi_port or on Solaris
\&  lock_file         "filename"              POSIX::tmpnam
.Ve
.PP
.Vb 1
\&  check_for_dead    \ed+                     30
.Ve
.PP
.Vb 2
\&  max_dequeue       \ed+                     undef
\&  check_for_dequeue \ed+                     undef
.Ve
.IP "max_servers" 4
.IX Item "max_servers"
The maximum number of child servers to start and maintain.
This does not apply to dequeue processes.
.IP "max_requests" 4
.IX Item "max_requests"
The number of client connections to receive before a
child terminates.
.IP "serialize" 4
.IX Item "serialize"
Determines whether the server serializes child connections.
Options are undef, flock, semaphore, or pipe.  Default is undef.
On multi_port servers or on servers running on Solaris, the
default is flock.  The flock option uses blocking exclusive
flock on the file specified in \fIlock_file\fR (see below).
The semaphore option uses IPC::Semaphore (thanks to Bennett
Todd) for giving some sample code.  The pipe option reads on a
pipe to choose the next.  the flock option should be the
most bulletproof while the pipe option should be the most
portable.  (Flock is able to reliquish the block if the
process dies between accept on the socket and reading
of the client connection \- semaphore and pipe do not)
.IP "lock_file" 4
.IX Item "lock_file"
Filename to use in flock serialized accept in order to
serialize the accept sequece between the children.  This
will default to a generated temporary filename.  If default
value is used the lock_file will be removed when the server
closes.
.IP "check_for_dead" 4
.IX Item "check_for_dead"
Seconds to wait before checking to see if a child died
without letting the parent know.
.IP "max_dequeue" 4
.IX Item "max_dequeue"
The maximum number of dequeue processes to start.  If a
value of zero or undef is given, no dequeue processes will
be started.  The number of running dequeue processes will
be checked by the check_for_dead variable.
.IP "check_for_dequeue" 4
.IX Item "check_for_dequeue"
Seconds to wait before forking off a dequeue process.  The
run_dequeue hook must be defined when using this setting.
It is intended to use the dequeue process to take care of
items such as mail queues.  If a value of undef is given,
no dequeue processes will be started.
.SH "CONFIGURATION FILE"
.IX Header "CONFIGURATION FILE"
\&\f(CW\*(C`Net::Server::PreFork\*(C'\fR allows for the use of a
configuration file to read in server parameters.  The format
of this conf file is simple key value pairs.  Comments and
white space are ignored.
.PP
.Vb 1
\&  #-------------- file test.conf --------------
.Ve
.PP
.Vb 2
\&  ### server information
\&  max_servers   80
.Ve
.PP
.Vb 1
\&  max_requests  1000
.Ve
.PP
.Vb 3
\&  ### user and group to become
\&  user        somebody
\&  group       everybody
.Ve
.PP
.Vb 4
\&  ### logging ?
\&  log_file    /var/log/server.log
\&  log_level   3
\&  pid_file    /tmp/server.pid
.Ve
.PP
.Vb 4
\&  ### access control
\&  allow       .+\e.(net|com)
\&  allow       domain\e.com
\&  deny        a.+
.Ve
.PP
.Vb 2
\&  ### background the process?
\&  background  1
.Ve
.PP
.Vb 4
\&  ### ports to bind
\&  host        127.0.0.1
\&  port        localhost:20204
\&  port        20205
.Ve
.PP
.Vb 2
\&  ### reverse lookups ?
\&  # reverse_lookups on
.Ve
.PP
.Vb 1
\&  #-------------- file test.conf --------------
.Ve
.SH "PROCESS FLOW"
.IX Header "PROCESS FLOW"
Process flow follows Net::Server until the loop phase.  At
this point \f(CW\*(C`max_servers\*(C'\fR are forked and wait for
connections.  When a child accepts a connection, finishs
processing a client, or exits, it relays that information to
the parent, which keeps track and makes sure there are
always \f(CW\*(C`max_servers\*(C'\fR running.
.SH "HOOKS"
.IX Header "HOOKS"
The PreForkSimple server has the following hooks in addition
to the hooks provided by the Net::Server base class.
See Net::Server
.ie n .IP """$self\->run_n_children_hook()""" 4
.el .IP "\f(CW$self\->run_n_children_hook()\fR" 4
.IX Item "$self->run_n_children_hook()"
This hook occurs at the top of run_n_children which is called
each time the server goes to start more child processes.  This
gives the parent to do a little of its own accountting (as desired).
Idea for this hook came from James FitzGibbon.
.ie n .IP """$self\->child_init_hook()""" 4
.el .IP "\f(CW$self\->child_init_hook()\fR" 4
.IX Item "$self->child_init_hook()"
This hook takes place immeditately after the child process
forks from the parent and before the child begins
accepting connections.  It is intended for any addiotional
chrooting or other security measures.  It is suggested
that all perl modules be used by this point, so that
the most shared memory possible is used.
.ie n .IP """$self\->child_finish_hook()""" 4
.el .IP "\f(CW$self\->child_finish_hook()\fR" 4
.IX Item "$self->child_finish_hook()"
This hook takes place immediately before the child tells
the parent that it is exiting.  It is intended for
saving out logged information or other general cleanup.
.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.
.SH "BUGS"
.IX Header "BUGS"
Tests don't seem to work on Win32.  Any ideas or patches would be welcome.
.SH "TO DO"
.IX Header "TO DO"
See Net::Server
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul T. Seamons paul@seamons.com
.SH "THANKS"
.IX Header "THANKS"
See Net::Server
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Please see also
Net::Server::Fork,
Net::Server::INET,
Net::Server::PreFork,
Net::Server::MultiType,
Net::Server::Single
Net::Server::SIG
Net::Server::Daemonize
Net::Server::Proto