.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTTP::Proxy::Engine 3pm"
.TH HTTP::Proxy::Engine 3pm "2022-12-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTTP::Proxy::Engine \- Generic child process manager engine for HTTP::Proxy
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use HTTP::Proxy;
\&
\&    # use the default engine for your system
\&    my $proxy = HTTP::Proxy\->new();
\&
\&    # choose one
\&    my $proxy = HTTP::Proxy\->new( engine => \*(AqOld\*(Aq );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The HTTP::Proxy::Engine class is a front-end to actual proxy
engine classes.
.PP
The role of an engine is to implement the main fork+serve loop
with all the required bookkeeping. This is also a good way to
test various implementation and/or try out new algorithms
without too much difficulties.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBnew()\fR" 4
.IX Item "new()"
Create a new engine. The parameter \f(CW\*(C`engine\*(C'\fR is used to decide which
kind of engine will be created. Other parameters are passed to the
underlying engine.
.Sp
This method also implement the subclasses constructor (they obviously
do not need the \f(CW\*(C`engine\*(C'\fR parameter).
.SH "CREATING YOUR OWN ENGINE"
.IX Header "CREATING YOUR OWN ENGINE"
It is possible to create one's own engine, by creating
a simple subclass of HTTP::Proxy::Engine with the following
methods:
.IP "\fBstart()\fR" 4
.IX Item "start()"
This method should handle any initialisation required when the
engine starts.
.IP "\fBrun()\fR" 4
.IX Item "run()"
This method is the main loop of the master process.
It defines how child processes are forked, checked and killed.
.Sp
The engine \s-1MUST\s0 have a \fBrun()\fR method, and it will be called again
and again until the proxy exits.
.Sp
\&\f(CW\*(C`$self\->proxy\->daemon\*(C'\fR returns the listening socket that can \f(CW\*(C`accept()\*(C'\fR
connections. The child must call \f(CW\*(C`$self\->proxy\->serve_connections()\*(C'\fR
on the returned socket to handle actual \s-1TCP\s0 connections.
.IP "\fBstop()\fR" 4
.IX Item "stop()"
This optional method should handle any cleanup procedures when the
engine stops (typically when the main proxy process is killed).
.PP
A subclass may also define a \f(CW%defaults\fR hash (with \f(CW\*(C`our\*(C'\fR) that
contains the default values for the fields used internaly.
.SH "METHODS PROVIDED TO SUBCLASSES"
.IX Header "METHODS PROVIDED TO SUBCLASSES"
HTTP::Proxy::Engine provides the following methods to its
subclasses:
.IP "\fBproxy()\fR" 4
.IX Item "proxy()"
Return the HTTP::Proxy object that runs the engine.
.IP "\fBmax_clients()\fR" 4
.IX Item "max_clients()"
Get or set the maximum number of \s-1TCP\s0 clients, that is to say
the maximum number of forked child process.
.Sp
Some engines may understand a value of \f(CW0\fR as \fIdo not fork at all\fR.
This is what HTTP::Proxy::Engine::Legacy does.
.ie n .IP "make_accessors( @names )" 4
.el .IP "make_accessors( \f(CW@names\fR )" 4
.IX Item "make_accessors( @names )"
Create accessors named after \f(CW@names\fR in the subclass package.
All accessors are read/write. This is a utility method.
.Sp
\&\fBThis is a class method.\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
Philippe \*(L"BooK\*(R" Bruhat, \f(CW\*(C`<book@cpan.org>\*(C'\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2005\-2015, Philippe Bruhat.
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it or modify it under
the same terms as Perl itself.