.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" 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 "docs::api::Apache2::SubProcess 3"
.TH docs::api::Apache2::SubProcess 3 "2013-04-16" "perl v5.16.3" "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"
Apache2::SubProcess \-\- Executing SubProcesses under mod_perl
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 1
\& use Apache2::SubProcess ();
\&
\& use Config;
\& use constant PERLIO_IS_ENABLED => $Config{useperlio};
\&
\& # pass @ARGV / read from the process
\& $command = "/tmp/argv.pl";
\& @argv = qw(foo bar);
\& $out_fh = $r\->spawn_proc_prog($command, \e@argv);
\& $output = read_data($out_fh);
\&
\& # pass environment / read from the process
\& $command = "/tmp/env.pl";
\& $r\->subprocess_env\->set(foo => "bar");
\& $out_fh = $r\->spawn_proc_prog($command);
\& $output = read_data($out_fh);
\&
\& # write to/read from the process
\& $command = "/tmp/in_out_err.pl";
\& ($in_fh, $out_fh, $err_fh) = $r\->spawn_proc_prog($command);
\& print $in_fh "hello\en";
\& $output = read_data($out_fh);
\& $error = read_data($err_fh);
\&
\& # helper function to work w/ and w/o perlio\-enabled Perl
\& sub read_data {
\& my ($fh) = @_;
\& my $data;
\& if (PERLIO_IS_ENABLED || IO::Select\->new($fh)\->can_read(10)) {
\& $data = <$fh>;
\& }
\& return defined $data ? $data : \*(Aq\*(Aq;
\& }
\&
\& # pass @ARGV but don\*(Aqt ask for any communication channels
\& $command = "/tmp/argv.pl";
\& @argv = qw(foo bar);
\& $r\->spawn_proc_prog($command, \e@argv);
.Ve
.SH "Description"
.IX Header "Description"
\&\f(CW\*(C`Apache2::SubProcess\*(C'\fR provides the Perl \s-1API\s0 for running and
communicating with processes spawned from mod_perl handlers.
.PP
At the moment it's possible to spawn only external program in a new
process. It's possible to provide other interfaces, e.g. executing a
sub-routine reference (via \f(CW\*(C`B::Deparse\*(C'\fR) and may be spawn a new
program in a thread (since the \s-1APR\s0 api includes \s-1API\s0 for spawning
threads, e.g. that's how it's running mod_cgi on win32).
.SH "API"
.IX Header "API"
.ie n .SS """spawn_proc_prog"""
.el .SS "\f(CWspawn_proc_prog\fP"
.IX Subsection "spawn_proc_prog"
Spawn a sub-process and return \s-1STD\s0 communication pipes:
.PP
.Vb 6
\& $r\->spawn_proc_prog($command);
\& $r\->spawn_proc_prog($command, \e@argv);
\& $out_fh = $r\->spawn_proc_prog($command);
\& $out_fh = $r\->spawn_proc_prog($command, \e@argv);
\& ($in_fh, $out_fh, $err_fh) = $r\->spawn_proc_prog($command);
\& ($in_fh, $out_fh, $err_fh) = $r\->spawn_proc_prog($command, \e@argv);
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
.PD 0
.ie n .IP "arg1: $command ( string )" 4
.el .IP "arg1: \f(CW$command\fR ( string )" 4
.IX Item "arg1: $command ( string )"
.PD
The command to be \f(CW\*(C`$exec()\*(C'\fR'ed.
.ie n .IP "opt arg2: ""\e@argv"" ( \s-1ARRAY\s0 ref )" 4
.el .IP "opt arg2: \f(CW\e@argv\fR ( \s-1ARRAY\s0 ref )" 4
.IX Item "opt arg2: @argv ( ARRAY ref )"
A reference to an array of arguments to be passed to the process as
the process' \f(CW\*(C`ARGV\*(C'\fR.
.IP "ret: ..." 4
.IX Item "ret: ..."
In \s-1VOID\s0 context returns no filehandles (all std streams to the spawned
process are closed).
.Sp
In \s-1SCALAR\s0 context returns the output filehandle of the spawned process
(the in and err std streams to the spawned process are closed).
.Sp
In \s-1LIST\s0 context returns the input, outpur and error filehandles of the
spawned process.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
It's possible to pass environment variables as well, by calling:
.PP
.Vb 1
\& $r\->subprocess_env\->set($key => $value);
.Ve
.PP
before spawning the subprocess.
.PP
There is an issue with reading from the read filehandle (\f(CW$in_fh\fR)):
.PP
A pipe filehandle returned under perlio-disabled Perl needs to call
\&\fIselect()\fR if the other end is not fast enough to send the data, since
the read is non-blocking.
.PP
A pipe filehandle returned under perlio-enabled Perl on the other hand
does the \fIselect()\fR internally, because it's really a filehandle opened
via \f(CW\*(C`:APR\*(C'\fR layer, which internally uses \s-1APR\s0 to communicate with the
pipe. The way \s-1APR\s0 is implemented Perl's \fIselect()\fR cannot be used with
it (mainly because \fIselect()\fR wants \fIfileno()\fR and \s-1APR\s0 is a crossplatform
implementation which hides the internal datastructure).
.PP
Therefore to write a portable code, you want to use select for
perlio-disabled Perl and do nothing for perlio-enabled Perl, hence you
can use something similar to the \f(CW\*(C`read_data()\*(C'\fR wrapper shown in the
Synopsis section.
.PP
Several examples appear in the Synopsis section.
.PP
\&\f(CW\*(C`spawn_proc_prog()\*(C'\fR is similar to \f(CW\*(C`fork()\*(C'\fR, but provides you a
better framework to communicate with that process and handles the
cleanups for you. But that means that just like \f(CW\*(C`fork()\*(C'\fR it gives you
a different process, so you don't use the current Perl interpreter in
that new process. If you try to use that method or fork to run a
high-performance parallel processing you should look elsewhere. You
could try Perl threads, but they are \fBvery\fR expensive to start if you
have a lot of things loaded into memory (since \f(CW\*(C`perl_clone()\*(C'\fR dups
almost everything in the perl land, but the opcode tree). In the
mod_perl \*(L"paradigm\*(R" this is much more expensive than fork, since
normally most of the time we have lots of perl things loaded into
memory. Most likely the best solution here is to offload the job to
PPerl or some other daemon, with the only added complexity of
communication.
.PP
To spawn a completely independent process, which will be able to run
after Apache has been shutdown and which won't prevent Apache from
restarting (releasing the ports Apache is listening to) call
\&\fIspawn_proc_prog()\fR in a void context and make the script detach and
close/reopen its communication streams. For example, spawn a process
as:
.PP
.Vb 2
\& use Apache2::SubProcess ();
\& $r\->spawn_proc_prog (\*(Aq/path/to/detach_script.pl\*(Aq, $args);
.Ve
.PP
and the \fI/path/to/detach_script.pl\fR contents are:
.PP
.Vb 4
\& # file:detach_script.pl
\& #!/usr/bin/perl \-w
\& use strict;
\& use warnings;
\&
\& use POSIX \*(Aqsetsid\*(Aq;
\&
\& chdir \*(Aq/\*(Aq or die "Can\*(Aqt chdir to /: $!";
\& open STDIN, \*(Aq/dev/null\*(Aq or die "Can\*(Aqt read /dev/null: $!";
\& open STDOUT, \*(Aq+>>\*(Aq, \*(Aq/path/to/apache/error_log\*(Aq
\& or die "Can\*(Aqt write to /dev/null: $!";
\& open STDERR, \*(Aq>&STDOUT\*(Aq or die "Can\*(Aqt dup stdout: $!";
\& setsid or die "Can\*(Aqt start a new session: $!";
\&
\& # run your code here or call exec to another program
.Ve
.PP
reopening (or closing) the \s-1STD\s0 streams and called \f(CW\*(C`setsid()\*(C'\fR makes
sure that the process is now fully detached from Apache and has a life
of its own. \f(CW\*(C`chdir()\*(C'\fR ensures that no partition is tied, in case you
need to remount it.
.SH "See Also"
.IX Header "See Also"
mod_perl 2.0 documentation.
.SH "Copyright"
.IX Header "Copyright"
mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.
.SH "Authors"
.IX Header "Authors"
The mod_perl development team and numerous
contributors.
y~or5J ={Eeu磝Qk ᯘG{?+]ן?wM3X^歌>{7پK>on\jy R g/=fOroNVv~Y+ NGuÝHWyw[eQʨSb> >}Gmx[o[<{Ϯ_qF vM IENDB`
