Apache2::SubProcess(3pm)

1docs::api::Apache2::SubUPsreorceCsosn(t3r)ibuted Perl Dodcoucmse:n:taaptii:o:nApache2::SubProcess(3)
2
3
4

NAME

6       Apache2::SubProcess -- Executing SubProcesses under mod_perl
7

Synopsis

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

Description

49       "Apache2::SubProcess" provides the Perl API for running and
50       communicating 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

API

59   "spawn_proc_prog"
60       Spawn a sub-process and return STD communication pipes:
61
62                                      $r->spawn_proc_prog($command);
63                                      $r->spawn_proc_prog($command, \@argv);
64         $out_fh                    = $r->spawn_proc_prog($command);
65         $out_fh                    = $r->spawn_proc_prog($command, \@argv);
66         ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command);
67         ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command, \@argv);
68
69       obj: $r ( "Apache2::RequestRec object" )
70       arg1: $command ( string )
71           The command to be "$exec()"'ed.
72
73       opt arg2: "\@argv" ( ARRAY ref )
74           A reference to an array of arguments to be passed to the process as
75           the process' "ARGV".
76
77       ret: ...
78           In VOID context returns no filehandles (all std streams to the
79           spawned process are closed).
80
81           In SCALAR context returns the output filehandle of the spawned
82           process (the in and err std streams to the spawned process are
83           closed).
84
85           In LIST context returns the input, outpur and error filehandles of
86           the spawned process.
87
88       since: 2.0.00
89
90       It's possible to pass environment variables as well, by calling:
91
92         $r->subprocess_env->set($key => $value);
93
94       before spawning the subprocess.
95
96       There is an issue with reading from the read filehandle ($in_fh)):
97
98       A pipe filehandle returned under perlio-disabled Perl needs to call
99       select() if the other end is not fast enough to send the data, since
100       the read is non-blocking.
101
102       A pipe filehandle returned under perlio-enabled Perl on the other hand
103       does the select() internally, because it's really a filehandle opened
104       via ":APR" layer, which internally uses APR to communicate with the
105       pipe. The way APR is implemented Perl's select() cannot be used with it
106       (mainly because select() wants fileno() and APR is a crossplatform
107       implementation which hides the internal datastructure).
108
109       Therefore to write a portable code, you want to use select for perlio-
110       disabled Perl and do nothing for perlio-enabled Perl, hence you can use
111       something similar to the "read_data()" wrapper shown in the Synopsis
112       section.
113
114       Several examples appear in the Synopsis section.
115
116       "spawn_proc_prog()" is similar to "fork()", but provides you a better
117       framework to communicate with that process and handles the cleanups for
118       you. But that means that just like "fork()" it gives you a different
119       process, so you don't use the current Perl interpreter in that new
120       process. If you try to use that method or fork to run a high-
121       performance parallel processing you should look elsewhere. You could
122       try Perl threads, but they are very expensive to start if you have a
123       lot of things loaded into memory (since "perl_clone()" dups almost
124       everything in the perl land, but the opcode tree). In the mod_perl
125       "paradigm" this is much more expensive than fork, since normally most
126       of the time we have lots of perl things loaded into memory. Most likely
127       the best solution here is to offload the job to PPerl or some other
128       daemon, with the only added complexity of communication.
129
130       To spawn a completely independent process, which will be able to run
131       after Apache has been shutdown and which won't prevent Apache from
132       restarting (releasing the ports Apache is listening to) call
133       spawn_proc_prog() in a void context and make the script detach and
134       close/reopen its communication streams. For example, spawn a process
135       as:
136
137         use Apache2::SubProcess ();
138         $r->spawn_proc_prog ('/path/to/detach_script.pl', $args);
139
140       and the /path/to/detach_script.pl contents are:
141
142         # file:detach_script.pl
143         #!/usr/bin/perl -w
144         use strict;
145         use warnings;
146
147         use POSIX 'setsid';
148
149         chdir '/'                or die "Can't chdir to /: $!";
150         open STDIN, '/dev/null'  or die "Can't read /dev/null: $!";
151         open STDOUT, '+>>', '/path/to/apache/error_log'
152             or die "Can't write to /dev/null: $!";
153         open STDERR, '>&STDOUT'  or die "Can't dup stdout: $!";
154         setsid or die "Can't start a new session: $!";
155
156         # run your code here or call exec to another program
157
158       reopening (or closing) the STD streams and called "setsid()" makes sure
159       that the process is now fully detached from Apache and has a life of
160       its own. "chdir()" ensures that no partition is tied, in case you need
161       to remount it.
162

Copyright

167       mod_perl 2.0 and its core modules are copyrighted under The Apache
168       Software License, Version 2.0.
169

Authors

171       The mod_perl development team and numerous contributors.
172
173
174
175perl v5.30.0                      2019-10-07 docs::api::Apache2::SubProcess(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors