1prefork(3) User Contributed Perl Documentation prefork(3)
2
3
4
6 prefork - Optimized module loading for forking or non-forking processes
7
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
53 The task of optimizing module loading in Perl tends to move in two dif‐
54 ferent 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
58 run-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 pro‐
67 files are diametrically opposed. What improves a situation for one
68 tends to make life worse for the other.
69
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
81 "prefork" is intended to be used in two different ways.
82
83 The first is by a module that wants to indicate that another module
84 should be loaded before forking. This is known as a "Loader".
85
86 The other is a script or module that will be initiating the forking. It
87 will tell prefork.pm that it is either going to fork, or is about to
88 fork, or for some other reason all modules previously mentioned by the
89 Loaders should be loaded immediately.
90
91 Usage as a Pragma
92
93 A Loader can register a module to be loaded using the following
94
95 use prefork 'My::Module';
96
97 The same thing can be done in such a way as to not require prefork
98 being installed, but taking advantage of it if it is.
99
100 eval "use prefork 'My::Module';";
101
102 A Forker can indicate that it will be forking with the following
103
104 use prefork ':enable';
105
106 In any use of "prefork" as a pragma, you can only pass a single value
107 as argument. Any additional arguments will be ignored. (This may throw
108 an error in future versions).
109
110 Compatbility with mod_perl and others
111
112 Part of the design of "prefork", and its minimalistic nature, is that
113 it is intended to work easily with existing modules, needing only small
114 changes.
115
116 For example, "prefork" itself will detect the $ENV{MOD_PERL} environ‐
117 ment variable and automatically start in forking mode.
118
119 prefork has support for integrating with third-party modules, such as
120 Class::Autouse. The "notify" function allows these run-time loaders to
121 register callbacks, to be called once prefork enters forking mode.
122
123 The synopsis entry above describes adding support for prefork.pm as a
124 dependency. To allow your third-party module loader without a depen‐
125 dency and only if it is installed use the following:
126
127 eval { require prefork; }
128 prefork::notify( \&function ) unless $@;
129
130 Using prefork.pm
131
132 From the Loader side, it is fairly simple. prefork becomes a dependency
133 for your module, and you use it as a pragma as documented above.
134
135 For the Forker, you have two options. Use as a dependency or optional
136 use.
137
138 In the dependency case, you add prefork as a dependency and use it as a
139 pragma with the ':enable' option.
140
141 To add only optional support for prefork, without requiring it to be
142 installed, you should wait until the moment just before you fork and
143 then call "prefork::enable" directly ONLY if it is loaded.
144
145 # Load modules if any use the prefork pragma.
146 prefork::enable() if $INC{prefork.pm};
147
148 This will cause the modules to be loaded ONLY if there are any modules
149 that need to be loaded. The main advantage of the dependency version is
150 that you only need to enable the module once, and not before each fork.
151
152 If you wish to have your own module leverage off the forking-detection
153 that prefork provides, you can also do the following.
154
155 use prefork;
156 if ( $prefork::FORKING ) {
157 # Complete some preparation task
158 }
159
160 Modules that are prefork-aware
161
162 mod_perl/mod_perl2
163 Class::Autouse
164
166 prefork $module
167
168 The 'prefork' function indicates that a module should be loaded before
169 the process will fork. If already in forking mode the module will be
170 loaded immediately.
171
172 Otherwise it will be added to a queue to be loaded later if it recieves
173 instructions that it is going to be forking.
174
175 Returns true on success, or dies on error.
176
177 enable
178
179 The "enable" function indicates to the prefork module that the process
180 is going to fork, possibly immediately.
181
182 When called, prefork.pm will immediately load all outstanding modules,
183 and will set a flag so that any further 'prefork' calls will load the
184 module at that time.
185
186 Returns true, dieing as normal is there is a problem loading a module.
187
188 notify &function
189
190 The "notify" function is used to integrate support for modules other
191 than prefork.pm itself.
192
193 A module loader calls the notify function, passing it a reference to a
194 "CODE" reference (either anon or a function reference). "prefork" will
195 store this CODE reference, and execute it immediately as soon as it
196 knows it is in forking-mode, but after it loads its own modules.
197
198 Callbacks are called in the order they are registered.
199
200 Normally, this will happen as soon as the "enable" function is called.
201
202 However, you should be aware that if prefork is already in preforking
203 mode at the time that the notify function is called, prefork.pm will
204 execute the function immediately.
205
206 This means that any third party module loader should be fully loaded
207 and initialised before the callback is provided to "notify".
208
209 Returns true if the function is stored, or dies if not passed a "CODE"
210 reference, or the callback is already set in the notify queue.
211
213 - Add checks for more pre-forking situations
214
216 Bugs should be always submitted via the CPAN bug tracker, located at
217
218 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=prefork>
219
220 For other issues, or commercial enhancement or support, contact the
221 author.
222
224 Adam Kennedy, <http://ali.as/>, cpan@ali.as
225
227 Thank you to Phase N Australia (<http://phase-n.com/>) for permitting
228 the open sourcing and release of this distribution.
229
230 Copyright (c) 2004 - 2005 Adam Kennedy.
231
232 This program is free software; you can redistribute it and/or modify it
233 under the same terms as Perl itself.
234
235 The full text of the license can be found in the LICENSE file included
236 with this module.
237
238
239
240perl v5.8.8 2007-11-22 prefork(3)