Filename | /usr/local/lib/perl5/5.24/XSLoader.pm |
Statements | Executed 0 statements in 55µs |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
16 | 16 | 16 | 11.6ms | 11.7ms | load | XSLoader::
0 | 0 | 0 | 0s | 0s | bootstrap_inherit | XSLoader::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | # Generated from XSLoader.pm.PL (resolved %Config::Config value) | ||||
2 | # This file is unique for every OS | ||||
3 | |||||
4 | package XSLoader; | ||||
5 | |||||
6 | $VERSION = "0.22"; | ||||
7 | |||||
8 | #use strict; | ||||
9 | |||||
10 | package DynaLoader; | ||||
11 | |||||
12 | # No prizes for guessing why we don't say 'bootstrap DynaLoader;' here. | ||||
13 | # NOTE: All dl_*.xs (including dl_none.xs) define a dl_error() XSUB | ||||
14 | boot_DynaLoader('DynaLoader') if defined(&boot_DynaLoader) && | ||||
15 | !defined(&dl_error); | ||||
16 | package XSLoader; | ||||
17 | |||||
18 | # spent 11.7ms (11.6+169µs) within XSLoader::load which was called 16 times, avg 733µs/call:
# once (3.80ms+0s) by IO::Socket::SSL::BEGIN@19 at line 401 of Net/SSLeay.pm
# once (1.13ms+0s) by Mail::SpamAssassin::Logger::Stderr::BEGIN@37 at line 36 of POSIX.pm
# once (736µs+0s) by NetAddr::IP::Lite::BEGIN@9 at line 875 of Socket.pm
# once (474µs+169µs) by Pod::Text::BEGIN@33 at line 10 of Encode.pm
# once (559µs+0s) by POSIX::BEGIN@11 at line 66 of Fcntl.pm
# once (520µs+0s) by Razor2::Logger::BEGIN@12 at line 64 of Sys/Syslog.pm
# once (512µs+0s) by Mail::SpamAssassin::BEGIN@65 at line 88 of re.pm
# once (501µs+0s) by Mail::SpamAssassin::HTML::BEGIN@30 at line 11 of HTML/Parser.pm
# once (493µs+0s) by Mail::SpamAssassin::Plugin::Hashcash::BEGIN@108 at line 255 of DB_File.pm
# once (489µs+0s) by Net::DNS::Resolver::Base::BEGIN@46 at line 22 of List/Util.pm
# once (452µs+0s) by Mail::SpamAssassin::Util::BEGIN@1750 at line 68 of File/Glob.pm
# once (444µs+0s) by IO::Handle::BEGIN@269 at line 11 of IO.pm
# once (384µs+0s) by Mail::SpamAssassin::Util::BEGIN@84 at line 14 of MIME/Base64.pm
# once (381µs+0s) by Pod::Usage::BEGIN@22 at line 17 of File/Spec/Unix.pm
# once (347µs+0s) by Data::Dumper::BEGIN@24 at line 34 of Data/Dumper.pm
# once (342µs+0s) by Sys::Hostname::BEGIN@16 at line 22 of Sys/Hostname.pm | ||||
19 | package DynaLoader; | ||||
20 | |||||
21 | my ($caller, $modlibname) = caller(); | ||||
22 | my $module = $caller; | ||||
23 | |||||
24 | if (@_) { | ||||
25 | $module = $_[0]; | ||||
26 | } else { | ||||
27 | $_[0] = $module; | ||||
28 | } | ||||
29 | |||||
30 | # work with static linking too | ||||
31 | my $boots = "$module\::bootstrap"; | ||||
32 | goto &$boots if defined &$boots; | ||||
33 | |||||
34 | goto \&XSLoader::bootstrap_inherit unless $module and defined &dl_load_file; | ||||
35 | |||||
36 | my @modparts = split(/::/,$module); | ||||
37 | my $modfname = $modparts[-1]; | ||||
38 | |||||
39 | my $modpname = join('/',@modparts); | ||||
40 | my $c = () = split(/::/,$caller,-1); | ||||
41 | $modlibname =~ s,[\\/][^\\/]+$,, while $c--; # Q&D basename | ||||
42 | # Does this look like a relative path? | ||||
43 | if ($modlibname !~ m{^/}) { | ||||
44 | # Someone may have a #line directive that changes the file name, or | ||||
45 | # may be calling XSLoader::load from inside a string eval. We cer- | ||||
46 | # tainly do not want to go loading some code that is not in @INC, | ||||
47 | # as it could be untrusted. | ||||
48 | # | ||||
49 | # We could just fall back to DynaLoader here, but then the rest of | ||||
50 | # this function would go untested in the perl core, since all @INC | ||||
51 | # paths are relative during testing. That would be a time bomb | ||||
52 | # waiting to happen, since bugs could be introduced into the code. | ||||
53 | # | ||||
54 | # So look through @INC to see if $modlibname is in it. A rela- | ||||
55 | # tive $modlibname is not a common occurrence, so this block is | ||||
56 | # not hot code. | ||||
57 | FOUND: { | ||||
58 | for (@INC) { | ||||
59 | if ($_ eq $modlibname) { | ||||
60 | last FOUND; | ||||
61 | } | ||||
62 | } | ||||
63 | # Not found. Fall back to DynaLoader. | ||||
64 | goto \&XSLoader::bootstrap_inherit; | ||||
65 | } | ||||
66 | } | ||||
67 | my $file = "$modlibname/auto/$modpname/$modfname.so"; | ||||
68 | |||||
69 | # print STDERR "XSLoader::load for $module ($file)\n" if $dl_debug; | ||||
70 | |||||
71 | my $bs = $file; | ||||
72 | $bs =~ s/(\.\w+)?(;\d*)?$/\.bs/; # look for .bs 'beside' the library | ||||
73 | |||||
74 | if (-s $bs) { # only read file if it's not empty | ||||
75 | # print STDERR "BS: $bs ($^O, $dlsrc)\n" if $dl_debug; | ||||
76 | eval { do $bs; }; | ||||
77 | warn "$bs: $@\n" if $@; | ||||
78 | goto \&XSLoader::bootstrap_inherit; | ||||
79 | } | ||||
80 | |||||
81 | goto \&XSLoader::bootstrap_inherit if not -f $file; | ||||
82 | |||||
83 | my $bootname = "boot_$module"; | ||||
84 | $bootname =~ s/\W/_/g; | ||||
85 | @DynaLoader::dl_require_symbols = ($bootname); | ||||
86 | |||||
87 | my $boot_symbol_ref; | ||||
88 | |||||
89 | # Many dynamic extension loading problems will appear to come from | ||||
90 | # this section of code: XYZ failed at line 123 of DynaLoader.pm. | ||||
91 | # Often these errors are actually occurring in the initialisation | ||||
92 | # C code of the extension XS file. Perl reports the error as being | ||||
93 | # in this perl code simply because this was the last perl code | ||||
94 | # it executed. | ||||
95 | |||||
96 | my $libref = dl_load_file($file, 0) or do { | ||||
97 | require Carp; | ||||
98 | Carp::croak("Can't load '$file' for module $module: " . dl_error()); | ||||
99 | }; | ||||
100 | push(@DynaLoader::dl_librefs,$libref); # record loaded object | ||||
101 | |||||
102 | $boot_symbol_ref = dl_find_symbol($libref, $bootname) or do { | ||||
103 | require Carp; | ||||
104 | Carp::croak("Can't find '$bootname' symbol in $file\n"); | ||||
105 | }; | ||||
106 | |||||
107 | push(@DynaLoader::dl_modules, $module); # record loaded module | ||||
108 | |||||
109 | boot: | ||||
110 | my $xs = dl_install_xsub($boots, $boot_symbol_ref, $file); | ||||
111 | |||||
112 | # See comment block above | ||||
113 | push(@DynaLoader::dl_shared_objects, $file); # record files loaded | ||||
114 | 1 | 55µs | 5 | 169µs | return &$xs(@_); # spent 169µs making 5 calls to Encode::define_encoding, avg 34µs/call |
115 | } | ||||
116 | |||||
117 | sub bootstrap_inherit { | ||||
118 | require DynaLoader; | ||||
119 | goto \&DynaLoader::bootstrap_inherit; | ||||
120 | } | ||||
121 | |||||
122 | 1; | ||||
123 | |||||
124 | |||||
125 | __END__ | ||||
126 | |||||
127 | =head1 NAME | ||||
128 | |||||
129 | XSLoader - Dynamically load C libraries into Perl code | ||||
130 | |||||
131 | =head1 VERSION | ||||
132 | |||||
133 | Version 0.22 | ||||
134 | |||||
135 | =head1 SYNOPSIS | ||||
136 | |||||
137 | package YourPackage; | ||||
138 | require XSLoader; | ||||
139 | |||||
140 | XSLoader::load(); | ||||
141 | |||||
142 | =head1 DESCRIPTION | ||||
143 | |||||
144 | This module defines a standard I<simplified> interface to the dynamic | ||||
145 | linking mechanisms available on many platforms. Its primary purpose is | ||||
146 | to implement cheap automatic dynamic loading of Perl modules. | ||||
147 | |||||
148 | For a more complicated interface, see L<DynaLoader>. Many (most) | ||||
149 | features of C<DynaLoader> are not implemented in C<XSLoader>, like for | ||||
150 | example the C<dl_load_flags>, not honored by C<XSLoader>. | ||||
151 | |||||
152 | =head2 Migration from C<DynaLoader> | ||||
153 | |||||
154 | A typical module using L<DynaLoader|DynaLoader> starts like this: | ||||
155 | |||||
156 | package YourPackage; | ||||
157 | require DynaLoader; | ||||
158 | |||||
159 | our @ISA = qw( OnePackage OtherPackage DynaLoader ); | ||||
160 | our $VERSION = '0.01'; | ||||
161 | bootstrap YourPackage $VERSION; | ||||
162 | |||||
163 | Change this to | ||||
164 | |||||
165 | package YourPackage; | ||||
166 | use XSLoader; | ||||
167 | |||||
168 | our @ISA = qw( OnePackage OtherPackage ); | ||||
169 | our $VERSION = '0.01'; | ||||
170 | XSLoader::load 'YourPackage', $VERSION; | ||||
171 | |||||
172 | In other words: replace C<require DynaLoader> by C<use XSLoader>, remove | ||||
173 | C<DynaLoader> from C<@ISA>, change C<bootstrap> by C<XSLoader::load>. Do not | ||||
174 | forget to quote the name of your package on the C<XSLoader::load> line, | ||||
175 | and add comma (C<,>) before the arguments (C<$VERSION> above). | ||||
176 | |||||
177 | Of course, if C<@ISA> contained only C<DynaLoader>, there is no need to have | ||||
178 | the C<@ISA> assignment at all; moreover, if instead of C<our> one uses the | ||||
179 | more backward-compatible | ||||
180 | |||||
181 | use vars qw($VERSION @ISA); | ||||
182 | |||||
183 | one can remove this reference to C<@ISA> together with the C<@ISA> assignment. | ||||
184 | |||||
185 | If no C<$VERSION> was specified on the C<bootstrap> line, the last line becomes | ||||
186 | |||||
187 | XSLoader::load 'YourPackage'; | ||||
188 | |||||
189 | If the call to C<load> is from C<YourPackage>, then that can be further | ||||
190 | simplified to | ||||
191 | |||||
192 | XSLoader::load(); | ||||
193 | |||||
194 | as C<load> will use C<caller> to determine the package. | ||||
195 | |||||
196 | =head2 Backward compatible boilerplate | ||||
197 | |||||
198 | If you want to have your cake and eat it too, you need a more complicated | ||||
199 | boilerplate. | ||||
200 | |||||
201 | package YourPackage; | ||||
202 | use vars qw($VERSION @ISA); | ||||
203 | |||||
204 | @ISA = qw( OnePackage OtherPackage ); | ||||
205 | $VERSION = '0.01'; | ||||
206 | eval { | ||||
207 | require XSLoader; | ||||
208 | XSLoader::load('YourPackage', $VERSION); | ||||
209 | 1; | ||||
210 | } or do { | ||||
211 | require DynaLoader; | ||||
212 | push @ISA, 'DynaLoader'; | ||||
213 | bootstrap YourPackage $VERSION; | ||||
214 | }; | ||||
215 | |||||
216 | The parentheses about C<XSLoader::load()> arguments are needed since we replaced | ||||
217 | C<use XSLoader> by C<require>, so the compiler does not know that a function | ||||
218 | C<XSLoader::load()> is present. | ||||
219 | |||||
220 | This boilerplate uses the low-overhead C<XSLoader> if present; if used with | ||||
221 | an antique Perl which has no C<XSLoader>, it falls back to using C<DynaLoader>. | ||||
222 | |||||
223 | =head1 Order of initialization: early load() | ||||
224 | |||||
225 | I<Skip this section if the XSUB functions are supposed to be called from other | ||||
226 | modules only; read it only if you call your XSUBs from the code in your module, | ||||
227 | or have a C<BOOT:> section in your XS file (see L<perlxs/"The BOOT: Keyword">). | ||||
228 | What is described here is equally applicable to the L<DynaLoader|DynaLoader> | ||||
229 | interface.> | ||||
230 | |||||
231 | A sufficiently complicated module using XS would have both Perl code (defined | ||||
232 | in F<YourPackage.pm>) and XS code (defined in F<YourPackage.xs>). If this | ||||
233 | Perl code makes calls into this XS code, and/or this XS code makes calls to | ||||
234 | the Perl code, one should be careful with the order of initialization. | ||||
235 | |||||
236 | The call to C<XSLoader::load()> (or C<bootstrap()>) calls the module's | ||||
237 | bootstrap code. For modules build by F<xsubpp> (nearly all modules) this | ||||
238 | has three side effects: | ||||
239 | |||||
240 | =over | ||||
241 | |||||
242 | =item * | ||||
243 | |||||
244 | A sanity check is done to ensure that the versions of the F<.pm> and the | ||||
245 | (compiled) F<.xs> parts are compatible. If C<$VERSION> was specified, this | ||||
246 | is used for the check. If not specified, it defaults to | ||||
247 | C<$XS_VERSION // $VERSION> (in the module's namespace) | ||||
248 | |||||
249 | =item * | ||||
250 | |||||
251 | the XSUBs are made accessible from Perl | ||||
252 | |||||
253 | =item * | ||||
254 | |||||
255 | if a C<BOOT:> section was present in the F<.xs> file, the code there is called. | ||||
256 | |||||
257 | =back | ||||
258 | |||||
259 | Consequently, if the code in the F<.pm> file makes calls to these XSUBs, it is | ||||
260 | convenient to have XSUBs installed before the Perl code is defined; for | ||||
261 | example, this makes prototypes for XSUBs visible to this Perl code. | ||||
262 | Alternatively, if the C<BOOT:> section makes calls to Perl functions (or | ||||
263 | uses Perl variables) defined in the F<.pm> file, they must be defined prior to | ||||
264 | the call to C<XSLoader::load()> (or C<bootstrap()>). | ||||
265 | |||||
266 | The first situation being much more frequent, it makes sense to rewrite the | ||||
267 | boilerplate as | ||||
268 | |||||
269 | package YourPackage; | ||||
270 | use XSLoader; | ||||
271 | use vars qw($VERSION @ISA); | ||||
272 | |||||
273 | BEGIN { | ||||
274 | @ISA = qw( OnePackage OtherPackage ); | ||||
275 | $VERSION = '0.01'; | ||||
276 | |||||
277 | # Put Perl code used in the BOOT: section here | ||||
278 | |||||
279 | XSLoader::load 'YourPackage', $VERSION; | ||||
280 | } | ||||
281 | |||||
282 | # Put Perl code making calls into XSUBs here | ||||
283 | |||||
284 | =head2 The most hairy case | ||||
285 | |||||
286 | If the interdependence of your C<BOOT:> section and Perl code is | ||||
287 | more complicated than this (e.g., the C<BOOT:> section makes calls to Perl | ||||
288 | functions which make calls to XSUBs with prototypes), get rid of the C<BOOT:> | ||||
289 | section altogether. Replace it with a function C<onBOOT()>, and call it like | ||||
290 | this: | ||||
291 | |||||
292 | package YourPackage; | ||||
293 | use XSLoader; | ||||
294 | use vars qw($VERSION @ISA); | ||||
295 | |||||
296 | BEGIN { | ||||
297 | @ISA = qw( OnePackage OtherPackage ); | ||||
298 | $VERSION = '0.01'; | ||||
299 | XSLoader::load 'YourPackage', $VERSION; | ||||
300 | } | ||||
301 | |||||
302 | # Put Perl code used in onBOOT() function here; calls to XSUBs are | ||||
303 | # prototype-checked. | ||||
304 | |||||
305 | onBOOT; | ||||
306 | |||||
307 | # Put Perl initialization code assuming that XS is initialized here | ||||
308 | |||||
309 | |||||
310 | =head1 DIAGNOSTICS | ||||
311 | |||||
312 | =over | ||||
313 | |||||
314 | =item C<Can't find '%s' symbol in %s> | ||||
315 | |||||
316 | B<(F)> The bootstrap symbol could not be found in the extension module. | ||||
317 | |||||
318 | =item C<Can't load '%s' for module %s: %s> | ||||
319 | |||||
320 | B<(F)> The loading or initialisation of the extension module failed. | ||||
321 | The detailed error follows. | ||||
322 | |||||
323 | =item C<Undefined symbols present after loading %s: %s> | ||||
324 | |||||
325 | B<(W)> As the message says, some symbols stay undefined although the | ||||
326 | extension module was correctly loaded and initialised. The list of undefined | ||||
327 | symbols follows. | ||||
328 | |||||
329 | =back | ||||
330 | |||||
331 | =head1 LIMITATIONS | ||||
332 | |||||
333 | To reduce the overhead as much as possible, only one possible location | ||||
334 | is checked to find the extension DLL (this location is where C<make install> | ||||
335 | would put the DLL). If not found, the search for the DLL is transparently | ||||
336 | delegated to C<DynaLoader>, which looks for the DLL along the C<@INC> list. | ||||
337 | |||||
338 | In particular, this is applicable to the structure of C<@INC> used for testing | ||||
339 | not-yet-installed extensions. This means that running uninstalled extensions | ||||
340 | may have much more overhead than running the same extensions after | ||||
341 | C<make install>. | ||||
342 | |||||
343 | |||||
344 | =head1 KNOWN BUGS | ||||
345 | |||||
346 | The new simpler way to call C<XSLoader::load()> with no arguments at all | ||||
347 | does not work on Perl 5.8.4 and 5.8.5. | ||||
348 | |||||
349 | |||||
350 | =head1 BUGS | ||||
351 | |||||
352 | Please report any bugs or feature requests via the perlbug(1) utility. | ||||
353 | |||||
354 | |||||
355 | =head1 SEE ALSO | ||||
356 | |||||
357 | L<DynaLoader> | ||||
358 | |||||
359 | |||||
360 | =head1 AUTHORS | ||||
361 | |||||
362 | Ilya Zakharevich originally extracted C<XSLoader> from C<DynaLoader>. | ||||
363 | |||||
364 | CPAN version is currently maintained by SE<eacute>bastien Aperghis-Tramoni | ||||
365 | E<lt>sebastien@aperghis.netE<gt>. | ||||
366 | |||||
367 | Previous maintainer was Michael G Schwern <schwern@pobox.com>. | ||||
368 | |||||
369 | |||||
370 | =head1 COPYRIGHT & LICENSE | ||||
371 | |||||
372 | Copyright (C) 1990-2011 by Larry Wall and others. | ||||
373 | |||||
374 | This program is free software; you can redistribute it and/or modify | ||||
375 | it under the same terms as Perl itself. | ||||
376 | |||||
377 | =cut |