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