SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from Fedora 27 perl-prefork-1.04-24.fc27.noarch.rpm

prefork

Section: User Contributed Perl Documentation (3)
Updated: 2009-07-21
Index 

NAME

prefork - Optimized module loading for forking or non-forking processes 

SYNOPSIS

In a module that normally delays module loading with require

  # Module Foo::Bar only uses This::That 25% of the time.  # We want to preload in in forking scenarios (like mod_perl), but  # we want to delay loading in non-forking scenarios (like CGI)  use prefork 'This::That';    sub do_something {      my $arg = shift;        # Load the module at run-time as normal      if ( $special_case ) {          require This::That;          This::That::blah(@_);      }  }    # Register a module to be loaded before forking directly  prefork::prefork('Module::Name');

In a script or module that is going to be forking.

  package Module::Forker;    # Enable forking mode  use prefork ':enable';    # Or call it directly  prefork::enable();

In a third-party run-time loader

  package Runtime::Loader;    use prefork ();  prefork::notify( \&load_everything );    ...    sub load_everything { ... }    1;
 

INTRODUCTION

The task of optimizing module loading in Perl tends to move in two differentdirections, depending on the context.

In a procedural context, such as scripts and CGI-type situations, you canimprove the load times and memory usage by loading a module at run-time,only once you are sure you will need it.

In the other common load profile for perl applications, the applicationwill start up and then fork off various worker processes. To take fulladvantage of memory copy-on-write features, the application should loadas many modules as possible before forking to prevent them consuming memoryin multiple worker processes.

Unfortunately, the strategies used to optimise for these two load profilesare diametrically opposed. What improves a situation for one tends tomake life worse for the other. 

DESCRIPTION

The "prefork" pragma is intended to allow module writers to optimisemodule loading for both scenarios with as little additional code aspossible.

prefork.pm is intended to serve as a central and optional marshallingpoint for state detection (are we running in compile-time or run-timemode) and to act as a relatively light-weight module loader. 

Loaders and Forkers

"prefork" is intended to be used in two different ways.

The first is by a module that wants to indicate that another module shouldbe loaded before forking. This is known as a ``Loader''.

The other is a script or module that will be initiating the forking. Itwill tell prefork.pm that it is either going to fork, or is about to fork,or for some other reason all modules previously mentioned by the Loadersshould be loaded immediately. 

Usage as a Pragma

A Loader can register a module to be loaded using the following

  use prefork 'My::Module';

The same thing can be done in such a way as to not require preforkbeing installed, but taking advantage of it if it is.

  eval "use prefork 'My::Module';";

A Forker can indicate that it will be forking with the following

  use prefork ':enable';

In any use of "prefork" as a pragma, you can only pass a single valueas argument. Any additional arguments will be ignored. (This may throwan error in future versions). 

Compatbility with mod_perl and others

Part of the design of "prefork", and its minimalistic nature, is that itis intended to work easily with existing modules, needing only smallchanges.

For example, "prefork" itself will detect the $ENV{MOD_PERL}environment variable and automatically start in forking mode.

prefork has support for integrating with third-party modules, such asClass::Autouse. The "notify" function allows these run-time loadersto register callbacks, to be called once prefork enters forking mode.

The synopsis entry above describes adding support for prefork.pm as adependency. To allow your third-party module loader without a dependencyand only if it is installed use the following:

  eval { require prefork; }  prefork::notify( \&function ) unless $@;
 

Using prefork.pm

From the Loader side, it is fairly simple. prefork becomes a dependencyfor your module, and you use it as a pragma as documented above.

For the Forker, you have two options. Use as a dependency or optional use.

In the dependency case, you add prefork as a dependency and use it as apragma with the ':enable' option.

To add only optional support for prefork, without requiring it to beinstalled, you should wait until the moment just before you fork and thencall "prefork::enable" directly ONLY if it is loaded.

  # Load modules if any use the prefork pragma.  prefork::enable() if $INC{prefork.pm};

This will cause the modules to be loaded ONLY if there are any modules thatneed to be loaded. The main advantage of the dependency version is that youonly need to enable the module once, and not before each fork.

If you wish to have your own module leverage off the forking-detection thatprefork provides, you can also do the following.

  use prefork;  if ( $prefork::FORKING ) {      # Complete some preparation task  }
 

Modules that are prefork-aware

mod_perl/mod_perl2
Class::Autouse
 

FUNCTIONS

 

prefork $module

The 'prefork' function indicates that a module should be loaded beforethe process will fork. If already in forking mode the module will beloaded immediately.

Otherwise it will be added to a queue to be loaded later if it recievesinstructions that it is going to be forking.

Returns true on success, or dies on error. 

enable

The "enable" function indicates to the prefork module that the process isgoing to fork, possibly immediately.

When called, prefork.pm will immediately load all outstanding modules, andwill set a flag so that any further 'prefork' calls will load the moduleat that time.

Returns true, dieing as normal is there is a problem loading a module. 

notify &function

The "notify" function is used to integrate support for modules other thanprefork.pm itself.

A module loader calls the notify function, passing it a reference to a"CODE" reference (either anon or a function reference). "prefork" willstore this CODE reference, and execute it immediately as soon as it knowsit is in forking-mode, but after it loads its own modules.

Callbacks are called in the order they are registered.

Normally, this will happen as soon as the "enable" function is called.

However, you should be aware that if prefork is already in preforkingmode at the time that the notify function is called, prefork.pm willexecute the function immediately.

This means that any third party module loader should be fully loaded andinitialised before the callback is provided to "notify".

Returns true if the function is stored, or dies if not passed a "CODE"reference, or the callback is already set in the notify queue. 

TO DO

- Add checks for more pre-forking situations 

SUPPORT

Bugs should be always submitted via the CPAN bug tracker, located at

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=prefork>

For other issues, or commercial enhancement or support, contact the author. 

AUTHOR

Adam Kennedy <adamkAATTcpan.org> 

COPYRIGHT

Thank you to Phase N Australia (<http://phase-n.com/>) forpermitting the open sourcing and release of this distribution.

Copyright 2004 - 2009 Adam Kennedy.

This program is free software; you can redistributeit and/or modify it under the same terms as Perl itself.

The full text of the license can be found in theLICENSE file included with this module.


 

Index

NAME
SYNOPSIS
INTRODUCTION
DESCRIPTION
Loaders and Forkers
Usage as a Pragma
Compatbility with mod_perl and others
Using prefork.pm
Modules that are prefork-aware
FUNCTIONS
prefork $module
enable
notify &function
TO DO
SUPPORT
AUTHOR
COPYRIGHT

This document was created byman2html,using the manual pages.