1docs::api::Apache2::SubUPsreorceCsosn(t3r)ibuted Perl Dodcoucmse:n:taaptii:o:nApache2::SubProcess(3)
2
3
4
6 Apache2::SubProcess -- Executing SubProcesses under mod_perl
7
9 use Apache2::SubProcess ();
10
11 use Config;
12 use constant PERLIO_IS_ENABLED => $Config{useperlio};
13
14 # pass @ARGV / read from the process
15 $command = "/tmp/argv.pl";
16 @argv = qw(foo bar);
17 $out_fh = $r->spawn_proc_prog($command, \@argv);
18 $output = read_data($out_fh);
19
20 # pass environment / read from the process
21 $command = "/tmp/env.pl";
22 $r->subprocess_env->set(foo => "bar");
23 $out_fh = $r->spawn_proc_prog($command);
24 $output = read_data($out_fh);
25
26 # write to/read from the process
27 $command = "/tmp/in_out_err.pl";
28 ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command);
29 print $in_fh "hello\n";
30 $output = read_data($out_fh);
31 $error = read_data($err_fh);
32
33 # helper function to work w/ and w/o perlio-enabled Perl
34 sub read_data {
35 my ($fh) = @_;
36 my $data;
37 if (PERLIO_IS_ENABLED ⎪⎪ IO::Select->new($fh)->can_read(10)) {
38 $data = <$fh>;
39 }
40 return defined $data ? $data : '';
41 }
42
43 # pass @ARGV but don't ask for any communication channels
44 $command = "/tmp/argv.pl";
45 @argv = qw(foo bar);
46 $r->spawn_proc_prog($command, \@argv);
47
49 "Apache2::SubProcess" provides the Perl API for running and communicat‐
50 ing with processes spawned from mod_perl handlers.
51
52 At the moment it's possible to spawn only external program in a new
53 process. It's possible to provide other interfaces, e.g. executing a
54 sub-routine reference (via "B::Deparse") and may be spawn a new program
55 in a thread (since the APR api includes API for spawning threads, e.g.
56 that's how it's running mod_cgi on win32).
57
59 "spawn_proc_prog"
60
61 Spawn a sub-process and return STD communication pipes:
62
63 $r->spawn_proc_prog($command);
64 $r->spawn_proc_prog($command, \@argv);
65 $out_fh = $r->spawn_proc_prog($command);
66 $out_fh = $r->spawn_proc_prog($command, \@argv);
67 ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command);
68 ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command, \@argv);
69
70 obj: $r ( "Apache2::RequestRec object" )
71 arg1: $command ( string )
72 The command to be "$exec()"'ed.
73
74 opt arg2: "\@argv" ( ARRAY ref )
75 A reference to an array of arguments to be passed to the process as
76 the process' "ARGV".
77
78 ret: ...
79 In VOID context returns no filehandles (all std streams to the
80 spawned process are closed).
81
82 In SCALAR context returns the output filehandle of the spawned
83 process (the in and err std streams to the spawned process are
84 closed).
85
86 In LIST context returns the input, outpur and error filehandles of
87 the spawned process.
88
89 since: 2.0.00
90
91 It's possible to pass environment variables as well, by calling:
92
93 $r->subprocess_env->set($key => $value);
94
95 before spawning the subprocess.
96
97 There is an issue with reading from the read filehandle ($in_fh)):
98
99 A pipe filehandle returned under perlio-disabled Perl needs to call
100 select() if the other end is not fast enough to send the data, since
101 the read is non-blocking.
102
103 A pipe filehandle returned under perlio-enabled Perl on the other hand
104 does the select() internally, because it's really a filehandle opened
105 via ":APR" layer, which internally uses APR to communicate with the
106 pipe. The way APR is implemented Perl's select() cannot be used with it
107 (mainly because select() wants fileno() and APR is a crossplatform
108 implementation which hides the internal datastructure).
109
110 Therefore to write a portable code, you want to use select for perlio-
111 disabled Perl and do nothing for perlio-enabled Perl, hence you can use
112 something similar to the "read_data()" wrapper shown in the Synopsis
113 section.
114
115 Several examples appear in the Synopsis section.
116
117 "spawn_proc_prog()" is similar to "fork()", but provides you a better
118 framework to communicate with that process and handles the cleanups for
119 you. But that means that just like "fork()" it gives you a different
120 process, so you don't use the current Perl interpreter in that new
121 process. If you try to use that method or fork to run a high-perfor‐
122 mance parallel processing you should look elsewhere. You could try Perl
123 threads, but they are very expensive to start if you have a lot of
124 things loaded into memory (since "perl_clone()" dups almost everything
125 in the perl land, but the opcode tree). In the mod_perl "paradigm" this
126 is much more expensive than fork, since normally most of the time we
127 have lots of perl things loaded into memory. Most likely the best solu‐
128 tion here is to offload the job to PPerl or some other daemon, with the
129 only added complexity of communication.
130
131 To spawn a completely independent process, which will be able to run
132 after Apache has been shutdown and which won't prevent Apache from
133 restarting (releasing the ports Apache is listening to) call
134 spawn_proc_prog() in a void context and make the script detach and
135 close/reopen its communication streams. For example, spawn a process
136 as:
137
138 use Apache2::SubProcess ();
139 $r->spawn_proc_prog ('/path/to/detach_script.pl', $args);
140
141 and the /path/to/detach_script.pl contents are:
142
143 # file:detach_script.pl
144 #!/usr/bin/perl -w
145 use strict;
146 use warnings;
147
148 use POSIX 'setsid';
149
150 chdir '/' or die "Can't chdir to /: $!";
151 open STDIN, '/dev/null' or die "Can't read /dev/null: $!";
152 open STDOUT, '+>>', '/path/to/apache/error_log'
153 or die "Can't write to /dev/null: $!";
154 open STDERR, '>&STDOUT' or die "Can't dup stdout: $!";
155 setsid or die "Can't start a new session: $!";
156
157 # run your code here or call exec to another program
158
159 reopening (or closing) the STD streams and called "setsid()" makes sure
160 that the process is now fully detached from Apache and has a life of
161 its own. "chdir()" ensures that no partition is tied, in case you need
162 to remount it.
163
165 mod_perl 2.0 documentation.
166
168 mod_perl 2.0 and its core modules are copyrighted under The Apache
169 Software License, Version 2.0.
170
172 The mod_perl development team and numerous contributors.
173
174
175
176perl v5.8.8 2006-11-19 docs::api::Apache2::SubProcess(3)