1prefork(3)            User Contributed Perl Documentation           prefork(3)
2
3
4

NAME

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

SYNOPSIS

9       In a module that normally delays module loading with require
10
11         # Module Foo::Bar only uses This::That 25% of the time.
12         # We want to preload in in forking scenarios (like mod_perl), but
13         # we want to delay loading in non-forking scenarios (like CGI)
14         use prefork 'This::That';
15
16         sub do_something {
17             my $arg = shift;
18
19             # Load the module at run-time as normal
20             if ( $special_case ) {
21                 require This::That;
22                 This::That::blah(@_);
23             }
24         }
25
26         # Register a module to be loaded before forking directly
27         prefork::prefork('Module::Name');
28
29       In a script or module that is going to be forking.
30
31         package Module::Forker;
32
33         # Enable forking mode
34         use prefork ':enable';
35
36         # Or call it directly
37         prefork::enable();
38
39       In a third-party run-time loader
40
41         package Runtime::Loader;
42
43         use prefork ();
44         prefork::notify( \&load_everything );
45
46         ...
47
48         sub load_everything { ... }
49
50         1;
51

INTRODUCTION

53       The task of optimizing module loading in Perl tends to move in two
54       different directions, depending on the context.
55
56       In a procedural context, such as scripts and CGI-type situations, you
57       can improve the load times and memory usage by loading a module at run-
58       time, only once you are sure you will need it.
59
60       In the other common load profile for perl applications, the application
61       will start up and then fork off various worker processes. To take full
62       advantage of memory copy-on-write features, the application should load
63       as many modules as possible before forking to prevent them consuming
64       memory in multiple worker processes.
65
66       Unfortunately, the strategies used to optimise for these two load
67       profiles are diametrically opposed. What improves a situation for one
68       tends to make life worse for the other.
69

DESCRIPTION

71       The "prefork" pragma is intended to allow module writers to optimise
72       module loading for both scenarios with as little additional code as
73       possible.
74
75       prefork.pm is intended to serve as a central and optional marshalling
76       point for state detection (are we running in compile-time or run-time
77       mode) and to act as a relatively light-weight module loader.
78
79   Loaders and Forkers
80       "prefork" is intended to be used in two different ways.
81
82       The first is by a module that wants to indicate that another module
83       should be loaded before forking. This is known as a "Loader".
84
85       The other is a script or module that will be initiating the forking. It
86       will tell prefork.pm that it is either going to fork, or is about to
87       fork, or for some other reason all modules previously mentioned by the
88       Loaders should be loaded immediately.
89
90   Usage as a Pragma
91       A Loader can register a module to be loaded using the following
92
93         use prefork 'My::Module';
94
95       The same thing can be done in such a way as to not require prefork
96       being installed, but taking advantage of it if it is.
97
98         eval "use prefork 'My::Module';";
99
100       A Forker can indicate that it will be forking with the following
101
102         use prefork ':enable';
103
104       In any use of "prefork" as a pragma, you can only pass a single value
105       as argument. Any additional arguments will be ignored. (This may throw
106       an error in future versions).
107
108   Compatibility with mod_perl and others
109       Part of the design of "prefork", and its minimalistic nature, is that
110       it is intended to work easily with existing modules, needing only small
111       changes.
112
113       For example, "prefork" itself will detect the $ENV{MOD_PERL}
114       environment variable and automatically start in forking mode.
115
116       prefork has support for integrating with third-party modules, such as
117       Class::Autouse. The "notify" function allows these run-time loaders to
118       register callbacks, to be called once prefork enters forking mode.
119
120       The synopsis entry above describes adding support for prefork.pm as a
121       dependency. To allow your third-party module loader without a
122       dependency and only if it is installed use the following:
123
124         eval { require prefork; }
125         prefork::notify( \&function ) unless $@;
126
127   Using prefork.pm
128       From the Loader side, it is fairly simple. prefork becomes a dependency
129       for your module, and you use it as a pragma as documented above.
130
131       For the Forker, you have two options. Use as a dependency or optional
132       use.
133
134       In the dependency case, you add prefork as a dependency and use it as a
135       pragma with the ':enable' option.
136
137       To add only optional support for prefork, without requiring it to be
138       installed, you should wait until the moment just before you fork and
139       then call "prefork::enable" directly ONLY if it is loaded.
140
141         # Load modules if any use the prefork pragma.
142         prefork::enable() if $INC{prefork.pm};
143
144       This will cause the modules to be loaded ONLY if there are any modules
145       that need to be loaded. The main advantage of the dependency version is
146       that you only need to enable the module once, and not before each fork.
147
148       If you wish to have your own module leverage off the forking-detection
149       that prefork provides, you can also do the following.
150
151         use prefork;
152         if ( $prefork::FORKING ) {
153             # Complete some preparation task
154         }
155
156   Modules that are prefork-aware
157       mod_perl/mod_perl2
158       Class::Autouse
159

FUNCTIONS

161   prefork $module
162       The 'prefork' function indicates that a module should be loaded before
163       the process will fork. If already in forking mode the module will be
164       loaded immediately.
165
166       Otherwise it will be added to a queue to be loaded later if it receives
167       instructions that it is going to be forking.
168
169       Returns true on success, or dies on error.
170
171   enable
172       The "enable" function indicates to the prefork module that the process
173       is going to fork, possibly immediately.
174
175       When called, prefork.pm will immediately load all outstanding modules,
176       and will set a flag so that any further 'prefork' calls will load the
177       module at that time.
178
179       Returns true, dying as normal is there is a problem loading a module.
180
181   notify &function
182       The "notify" function is used to integrate support for modules other
183       than prefork.pm itself.
184
185       A module loader calls the notify function, passing it a reference to a
186       "CODE" reference (either anon or a function reference). "prefork" will
187       store this CODE reference, and execute it immediately as soon as it
188       knows it is in forking-mode, but after it loads its own modules.
189
190       Callbacks are called in the order they are registered.
191
192       Normally, this will happen as soon as the "enable" function is called.
193
194       However, you should be aware that if prefork is already in preforking
195       mode at the time that the notify function is called, prefork.pm will
196       execute the function immediately.
197
198       This means that any third party module loader should be fully loaded
199       and initialised before the callback is provided to "notify".
200
201       Returns true if the function is stored, or dies if not passed a "CODE"
202       reference, or the callback is already set in the notify queue.
203

TO DO

205       - Add checks for more pre-forking situations
206

SUPPORT

208       Bugs should be always submitted via the CPAN bug tracker, located at
209
210       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=prefork>
211
212       For other issues, or commercial enhancement or support, contact the
213       author.
214

AUTHOR

216       Adam Kennedy <adamk@cpan.org>
217
219       Thank you to Phase N Australia (<http://phase-n.com/>) for permitting
220       the open sourcing and release of this distribution.
221
222       Copyright 2004 - 2009 Adam Kennedy.
223
224       This program is free software; you can redistribute it and/or modify it
225       under the same terms as Perl itself.
226
227       The full text of the license can be found in the LICENSE file included
228       with this module.
229
230
231
232perl v5.36.0                      2022-07-22                        prefork(3)
Impressum