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