home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-perl-addon-1.4.9-installer.exe / SubProcess.pm < prev    next >
Encoding:
Perl POD Document  |  2004-09-23  |  4.5 KB  |  180 lines
  1. # 
  2. # /*
  3. #  * *********** WARNING **************
  4. #  * This file generated by ModPerl::WrapXS/0.01
  5. #  * Any changes made here will be lost
  6. #  * ***********************************
  7. #  * 01: lib/ModPerl/Code.pm:701
  8. #  * 02: O:\147xampp\sources\mod_perl-1.99_16\blib\lib/ModPerl/WrapXS.pm:584
  9. #  * 03: O:\147xampp\sources\mod_perl-1.99_16\blib\lib/ModPerl/WrapXS.pm:1100
  10. #  * 04: Makefile.PL:335
  11. #  * 05: Makefile.PL:283
  12. #  * 06: Makefile.PL:51
  13. #  */
  14. # 
  15.  
  16.  
  17. package Apache::SubProcess;
  18.  
  19. use strict;
  20. use warnings FATAL => 'all';
  21.  
  22.  
  23.  
  24. use Apache::XSLoader ();
  25. our $VERSION = '0.01';
  26. Apache::XSLoader::load __PACKAGE__;
  27.  
  28. use APR::PerlIO ();
  29.  
  30.  
  31. 1;
  32. __END__
  33.  
  34. =head1 NAME
  35.  
  36. Apache::SubProcess -- Executing SubProcesses under mod_perl
  37.  
  38.  
  39.  
  40.  
  41.  
  42. =head1 Synopsis
  43.  
  44.   use Apache::SubProcess ();
  45.   
  46.   use Config;
  47.   use constant PERLIO_IS_ENABLED => $Config{useperlio};
  48.   
  49.   # pass @ARGV / read from the process
  50.   $command = "/tmp/argv.pl";
  51.   @argv = qw(foo bar);
  52.   $out_fh = $r->spawn_proc_prog($command, \@argv);
  53.   $output = read_data($out_fh);
  54.   
  55.   # pass environment / read from the process
  56.   $command = "/tmp/env.pl";
  57.   $r->subprocess_env->set(foo => "bar");
  58.   $out_fh = $r->spawn_proc_prog($command);
  59.   $output = read_data($out_fh);
  60.   
  61.   # write to/read from the process
  62.   $command = "/tmp/in_out_err.pl";
  63.   ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command);
  64.   print $in_fh "hello\n";
  65.   $output = read_data($out_fh);
  66.   $error  = read_data($err_fh);
  67.   
  68.   # helper function to work w/ and w/o perlio-enabled Perl
  69.   sub read_data {
  70.       my($fh) = @_;
  71.       my $data;
  72.       if (PERLIO_IS_ENABLED || IO::Select->new($fh)->can_read(10)) {
  73.           $data = <$fh>;
  74.       }
  75.       return defined $data ? $data : '';
  76.   }
  77.  
  78.  
  79.  
  80.  
  81. =head1 Description
  82.  
  83. C<Apache::SubProcess> provides the Perl API for running and
  84. communicating with processes spawned from mod_perl handlers.
  85.  
  86. At the moment it's possible to spawn only external program in a new
  87. process. It's possible to provide other interfaces, e.g. executing a
  88. sub-routine reference (via C<B::Deparse>) and may be spawn a new
  89. program in a thread (since the APR api includes API for spawning
  90. threads, e.g. that's how it's running mod_cgi on win32).
  91.  
  92.  
  93. =head1 API
  94.  
  95.  
  96. =head2 C<spawn_proc_prog>
  97.  
  98. Spawn a sub-process and return STD communication pipes:
  99.  
  100.   $out_fh                    = $r->spawn_proc_prog($command);
  101.   $out_fh                    = $r->spawn_proc_prog($command, \@argv);
  102.   ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command);
  103.   ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command, \@argv);
  104.  
  105. =over 4
  106.  
  107. =item obj: C<$r>
  108. ( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
  109.  
  110. =item arg1: C<$command> ( string )
  111.  
  112. The command to be C<$exec()>'ed.
  113.  
  114. =item opt arg2: C<\@argv> ( ARRAY ref )
  115.  
  116. A reference to an array of arguments to be passed to the process as
  117. the process' C<ARGV>.
  118.  
  119. =item ret: ...
  120.  
  121. In SCALAR context returns the output filehandle of the spawned
  122. process.
  123.  
  124. In LIST context returns the input, outpur and error filehandles of the
  125. spawned process.
  126.  
  127. =item since: 1.99_15
  128.  
  129. =back
  130.  
  131. It's possible to pass environment variables as well, by calling:
  132.  
  133.   $r->subprocess_env->set($key => $value);
  134.  
  135. before spawning the subprocess.
  136.  
  137. There is an issue with reading from the read filehandle (C<$in_fh>)):
  138.  
  139. A pipe filehandle returned under perlio-disabled Perl needs to call
  140. select() if the other end is not fast enough to send the data, since
  141. the read is non-blocking.
  142.  
  143. A pipe filehandle returned under perlio-enabled Perl on the other hand
  144. does the select() internally, because it's really a filehandle opened
  145. via C<:APR> layer, which internally uses APR to communicate with the
  146. pipe. The way APR is implemented Perl's select() cannot be used with
  147. it (mainly because select() wants fileno() and APR is a crossplatform
  148. implementation which hides the internal datastructure).
  149.  
  150. Therefore to write a portable code, you want to use select for
  151. perlio-disabled Perl and do nothing for perlio-enabled Perl, hence you
  152. can use something similar to the C<read_data()> wrapper shown in the
  153. L<Synopsis|/Synopsis> section.
  154.  
  155. Several examples appear in the L<Synopsis|/Synopsis> section.
  156.  
  157.  
  158.  
  159. =head1 See Also
  160.  
  161. L<mod_perl 2.0 documentation|docs::2.0::index>.
  162.  
  163.  
  164.  
  165.  
  166. =head1 Copyright
  167.  
  168. mod_perl 2.0 and its core modules are copyrighted under
  169. The Apache Software License, Version 2.0.
  170.  
  171.  
  172.  
  173.  
  174. =head1 Authors
  175.  
  176. L<The mod_perl development team and numerous
  177. contributors|about::contributors::people>.
  178.  
  179. =cut
  180.