apachaepamcohdepmeordl-p1e0r1l.-11~02U1:s.:e1mr~o2dC:o:pnmetorrdli-bp2ue.tr0el.d-22:P.:e0dr.ol2c:sD::od:coaucpmsie::n::taAapptiai:co:hnAep2a:c:hSeu2b:P:rSoucbePsrso(c3e)ss(3)

NAME
       Apache2::SubProcess - Executing SubProcesses under modperl

SSyynnooppssiiss
         use Apache2::SubProcess ();

         use Config;
         use constant PERLIOISENABLED => $Config{useperlio};

         # pass @ARGV / read from the process
         $command = "/tmp/argv.pl";
         @argv = qw(foo bar);
         $outfh = $r->spawnprocprog($command, \@argv);
         $output = readdata($outfh);

         # pass environment / read from the process
         $command = "/tmp/env.pl";
         $r->subprocessenv->set(foo => "bar");
         $outfh = $r->spawnprocprog($command);
         $output = readdata($outfh);

         # write to/read from the process
         $command = "/tmp/inouterr.pl";
         ($infh, $outfh, $errfh) = $r->spawnprocprog($command);
         print $infh "hello\n";
         $output = readdata($outfh);
         $error  = readdata($errfh);

         # helper function to work w/ and w/o perlio-enabled Perl
         sub readdata {
             my ($fh) = @;
             my $data;
             if (PERLIOISENABLED || IO::Select->new($fh)->canread(10)) {
                 $data = <$fh>;
             }
             return defined $data ? $data : '';
         }

         # pass @ARGV but don't ask for any communication channels
         $command = "/tmp/argv.pl";
         @argv = qw(foo bar);
         $r->spawnprocprog($command, \@argv);

DDeessccrriippttiioonn
       "Apache2::SubProcess" provides the Perl API for running and
       communicating with processes spawned from modperl handlers.

       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 "B::Deparse") and may be spawn a new program
       in a thread (since the APR api includes API for spawning threads, e.g.
       that's how it's running modcgi on win32).

AAPPII
       ""ssppaawwnnpprrooccpprroogg""

       Spawn a sub-process and return STD communication pipes:

                                      $r->spawnprocprog($command);
                                      $r->spawnprocprog($command, \@argv);
         $outfh                    = $r->spawnprocprog($command);
         $outfh                    = $r->spawnprocprog($command, \@argv);
         ($infh, $outfh, $errfh) = $r->spawnprocprog($command);
         ($infh, $outfh, $errfh) = $r->spawnprocprog($command, \@argv);

       obj: $r ( "Apache2::RequestRec object" )
       arg1: $command ( string )
           The command to be "$exec()"'ed.

       opt arg2: "\@argv" ( ARRAY ref )
           A reference to an array of arguments to be passed to the process as
           the process' "ARGV".

       ret: ...
           In VOID context returns no filehandles (all std streams to the
           spawned process are closed).

           In SCALAR context returns the output filehandle of the spawned
           process (the in and err std streams to the spawned process are
           closed).

           In LIST context returns the input, outpur and error filehandles of
           the spawned process.

       since: 2.0.00

       It's possible to pass environment variables as well, by calling:

         $r->subprocessenv->set($key => $value);

       before spawning the subprocess.

       There is an issue with reading from the read filehandle ($infh)):

       A pipe filehandle returned under perlio-disabled Perl needs to call
       select() if the other end is not fast enough to send the data, since
       the read is non-blocking.

       A pipe filehandle returned under perlio-enabled Perl on the other hand
       does the select() internally, because it's really a filehandle opened
       via ":APR" layer, which internally uses APR to communicate with the
       pipe. The way APR is implemented Perl's select() cannot be used with it
       (mainly because select() wants fileno() and APR is a crossplatform
       implementation which hides the internal datastructure).

       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 "readdata()" wrapper shown in the Synopsis
       section.

       Several examples appear in the Synopsis section.

       "spawnprocprog()" is similar to "fork()", but provides you a better
       framework to communicate with that process and handles the cleanups for
       you. But that means that just like "fork()" 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 vveerryy expensive to start if you have a
       lot of things loaded into memory (since "perlclone()" dups almost
       everything in the perl land, but the opcode tree). In the modperl
       "paradigm" 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.

       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
       spawnprocprog() in a void context and make the script detach and
       close/reopen its communication streams. For example, spawn a process
       as:

         use Apache2::SubProcess ();
         $r->spawnprocprog ('/path/to/detachscript.pl', $args);

       and the /path/to/detachscript.pl contents are:

         # file:detachscript.pl
         #!/usr/bin/perl -w
         use strict;
         use warnings;

         use POSIX 'setsid';

         chdir '/'                or die "Can't chdir to /: $!";
         open STDIN, '/dev/null'  or die "Can't read /dev/null: $!";
         open STDOUT, '+>>', '/path/to/apache/errorlog'
             or die "Can't write to /dev/null: $!";
         open STDERR, '>&STDOUT'  or die "Can't dup stdout: $!";
         setsid or die "Can't start a new session: $!";

         # run your code here or call exec to another program

       reopening (or closing) the STD streams and called "setsid()" makes sure
       that the process is now fully detached from Apache and has a life of
       its own. "chdir()" ensures that no partition is tied, in case you need
       to remount it.

SSeeee AAllssoo
       modperl 2.0 documentation.

CCooppyyrriigghhtt
       modperl 2.0 and its core modules are copyrighted under The Apache
       Software License, Version 2.0.

AAuutthhoorrss
       The modperl development team and numerous contributors.



perlavp5a.c8h.e8modperl-101.1~2::modp2e0r0l5-21.00-.220::docs::api::Apache2::SubProcess(3)