perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/api/mod_perl-2.0/Apache SubProcess.pod
Date Wed, 21 Aug 2002 17:23:24 GMT
stas        2002/08/21 10:23:24

  Modified:    src/docs/2.0/api config.cfg
  Added:       src/docs/2.0/api/mod_perl-2.0/Apache SubProcess.pod
  Log:
  - start Apache::SubProcess documentation
  - sort the pods order
  
  Revision  Changes    Path
  1.10      +5 -4      modperl-docs/src/docs/2.0/api/config.cfg
  
  Index: config.cfg
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/config.cfg,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- config.cfg	22 Jul 2002 15:21:51 -0000	1.9
  +++ config.cfg	21 Aug 2002 17:23:24 -0000	1.10
  @@ -15,11 +15,12 @@
   
       group    => 'Apache',
       chapters => [qw(
  +        mod_perl-2.0/Apache/Log.pod
  +        mod_perl-2.0/Apache/Reload.pod
           mod_perl-2.0/Apache/RequestRec.pod
           mod_perl-2.0/Apache/ServerUtil.pod
  -        mod_perl-2.0/Apache/Log.pod
  +        mod_perl-2.0/Apache/SubProcess.pod
           mod_perl-2.0/Apache/compat.pod
  -        mod_perl-2.0/Apache/Reload.pod
       )],
   
       group    => 'APR',
  @@ -30,11 +31,11 @@
   
       group    => 'ModPerl',
       chapters => [qw(
  -        ModPerl-Registry/ModPerl/Registry.pod
           ModPerl-Registry/ModPerl/PerlRun.pod
  +        ModPerl-Registry/ModPerl/Registry.pod
  +        ModPerl-Registry/ModPerl/RegistryBB.pod
           ModPerl-Registry/ModPerl/RegistryCooker.pod
           ModPerl-Registry/ModPerl/RegistryLoader.pod
  -        ModPerl-Registry/ModPerl/RegistryBB.pod
       )],
   
   
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/mod_perl-2.0/Apache/SubProcess.pod
  
  Index: SubProcess.pod
  ===================================================================
  =head1 NAME
  
  Apache::SubProcess -- Executing SubProcesses from mod_perl
  
  =head1 SYNOPSIS
  
    use Apache::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 = Apache::SubProcess::spawn_proc_prog($r, $command, \@argv);
    $output = read_data($out_fh);
  
    # pass environment / read from the process
    $command = "/tmp/env.pl";
    $r->subprocess_env->set(foo => "bar");
    $out_fh = Apache::SubProcess::spawn_proc_prog($r, $command);
    $output = read_data($out_fh);
  
    # write to/read from the process
    $command = "/tmp/in_out_err.pl";
    ($in_fh, $out_fh, $err_fh) = 
        Apache::SubProcess::spawn_proc_prog($r, $command);
    print $in_fh "hello\n";
    $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 : '';
    }
  
  =head1 DESCRIPTION
  
  C<Apache::SubProcess> provides the Perl API for running and
  communicating with processes spawned from mod_perl handlers.
  
  =head1 API
  
  =head2 spawn_proc_prog()
  
    $out_fh = 
        Apache::SubProcess::spawn_proc_prog($r, $command, [\@argv]);
    ($in_fh, $out_fh, $err_fh) = 
        Apache::SubProcess::spawn_proc_prog($r, $command, [\@argv]);
  
  spawn_proc_prog() spawns a sub-process which exec()'s C<$command> and
  returns the output pipe filehandle in the scalar context, or input,
  output and error pipe filehandles in the list context. Using these
  three pipes it's possible to communicate with the spawned process.
  
  The third optional argument is a reference to an array which if passed
  becomes ARGV to the spawned program.
  
  It's possible to pass environment variables as well, by calling:
  
    $r->subprocess_env->set($key => $value);
  
  before spawning the subprocess.
  
  There is an issue with reading from the read filehandle (C<$in_fh>)):
  
  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 C<: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 read_data() wrapper shown in the
  L<SYNOPSIS> section.
  
  =cut
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message