2010/3/2 Torsten Förtsch <torsten.foert...@gmx.net>:
> Not much, just a few problems solved. Comments are welcome.
Looks very cool! I know there are a couple of hooks in APR that
aren't mapped into mod_perl space yet, such as apr_proc_create().
Have you thought about adding those to mod_perl core for a more native
and portable forking solution?
>
> NAME
> ModPerl2::Tools - a few hopefully useful tools
>
> SYNOPSIS
> use ModPerl2::Tools;
>
> ModPerl2::Tools::spawn +{keep_fd=>[3,4,7], survive=>1}, sub {...};
> ModPerl2::Tools::spawn +{keep_fd=>[3,4,7], survive=>1}, qw/bash -c .../;
>
> ModPerl2::Tools::safe_die $status;
> $r->safe_die($status);
> $f->safe_die($status);
>
> $content=ModPerl2::Tools::fetch_url $url;
> $content=$r->fetch_url($url);
>
> INSTALLATION
> perl Makefile.PL
> make
> make test
> make install
>
> DESCRIPTION
> This module is a collection of functions and methods that I found useful
> when working with "mod_perl". I work mostly under Linux. So, I don't
> expect all of these functions to work on other operating systems.
>
> Forking off long running processes
> Sometimes one needs to spawn off a long running process as the result of
> a request. Under modperl this is not as simple as calling "fork" because
> that way all open file descriptors would be inherited by the child and,
> more subtle, the long running process would be killed when the
> administrator shuts down the web server. The former is usually
> considered a security issue, the latter a design decision.
>
> There is already $r->spawn_proc_prog that serves a similar purpose as
> the "spawn" function. However, "spawn_proc_prog" is not usable for long
> running processes because it kills the children after a certain timeout.
>
> Solution
> $pid=ModPerl2::Tools::spawn \%options, $subroutine, @parameters;
>
> or
>
> $pid=ModPerl2::Tools::spawn \%options, @command_line;
>
> "spawn" expects as the first parameter an options hash reference. The
> second parameter may be a code reference or a string.
>
> In case of a code ref no other program is executed but the subroutine is
> called instead. The remaining parameters are passed to this function.
>
> Note, the perl environment under modperl differs in certain ways from a
> normal perl environment. For example %ENV is not bound to the C-level
> "environ". These modifications are not undone by this module. So, it's
> generally better to execute another perl interpreter instead of using
> the $subroutine feature.
>
> The options parameter accepts these options:
>
> keep_fd => \...@fds
> here an array of file descriptor numbers (not file handles) is
> expected. All other file descriptors except for the listed and file
> descriptor 2 (STDERR) are closed before calling $subroutine or
> executing @command_line.
>
> survive => $boolean
> if passed "false" the created process will be killed when Apache
> shuts down. if true it will survive an Apache restart.
>
> The return code on success is the PID of the process. On failure "undef"
> or an empty string is returned.
>
> The created process is not related as a child process to the current
> apache child.
>
> Serving "ErrorDocument"s
> Triggering "ErrorDocument"s from a registry script or even more from an
> output filter is not simple. The normal way as a handler is
>
> return Apache2::Const::STATUS;
>
> This does not work for registry scripts. An output filter even if it
> returns a status can trigger only a "SERVER_ERROR".
>
> The main interface to enter standard error processing in Apache is
> "ap_die()" at C-level. Its Perl interface is hidden in Apache2::HookRun.
>
> There is one case when an error message cannot be sent to the user. This
> happens if the HTTP headers are already on the wire. Then it is too
> late.
>
> The various flavors of "safe_die()" take this into account.
>
> ModPerl2::Tools::safe_die $status
> This function is designed to be called from registry scripts. It
> uses Apache2::RequestUtil->request to fetch the current request
> object. So,
>
> PerlOption +GlobalRequest
>
> must be enabled.
>
> Usage example:
>
> ModPerl2::Tools::safe_die 401;
> exit 0;
>
> $r->safe_die($status)
> $f->safe_die($status)
> These 2 methods are to be used if a request object or a filter
> object are available.
>
> Usage from within a filter:
>
> package My::Filter;
> use strict;
> use warnings;
>
> use ModPerl2::Tools;
> use base 'Apache2::Filter';
>
> sub handler : FilterRequestHandler {
> my ($f, $bb)=...@_;
> return $f->safe_die(410);
> }
>
> The filter flavor removes the current filter from the request's
> output filter chain.
>
> Fetching the content of another document
> Sometimes a handler or a filter needs the content of another document in
> the web server's realm. Apache provides subrequests for this purpose.
>
> The 2 "fetch_url" variants use a subrequest to fetch the content of
> another document. The document can even be fetched via "mod_proxy" from
> another server. However, fetching a document directly as with LWP for
> example is not (yet) possible.
>
> "ModPerl2::Tools::fetch_url" needs
>
> PerlOption +GlobalRequest
>
> Usage:
>
> $content=ModPerl2::Tools::fetch_url '/some/where?else=42';
>
> $content=$r->fetch_url('/some/where?else=42');
>
> EXPORTS
> None.
>
> SEE ALSO
> <http://perl.apache.org>
>
> AUTHOR
> Torsten Förtsch, <torsten.foert...@gmx.net>
>
> COPYRIGHT AND LICENSE
> Copyright (C) 2010 by Torsten Förtsch
>
> This library is free software; you can redistribute it and/or modify it
> under the same terms as Perl itself.
>
>
> Torsten Förtsch
>
> --
> Need professional modperl support? Hire me! (http://foertsch.name)
>
> Like fantasy? http://kabatinte.net
>
