[Summary view] [Print] [Text view]

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