xsloader.html

来自「perl教程」· HTML 代码 · 共 305 行 · 第 1/2 页

What is described here is equally applicable to the <a href="../lib/DynaLoader.html">DynaLoader</a>
interface.</em></p>
<p>A sufficiently complicated module using XS would have both Perl code (defined
in <em>YourPackage.pm</em>) and XS code (defined in <em>YourPackage.xs</em>).  If this
Perl code makes calls into this XS code, and/or this XS code makes calls to
the Perl code, one should be careful with the order of initialization.</p>
<p>The call to <a href="#item_load"><code>XSLoader::load()</code></a> (or <code>bootstrap()</code>) has three side effects:</p>
<ul>
<li>
<p>if <code>$VERSION</code> was specified, a sanity check is done to ensure that the
versions of the <em>.pm</em> and the (compiled) <em>.xs</em> parts are compatible;</p>
</li>
<li>
<p>the XSUBs are made accessible from Perl;</p>
</li>
<li>
<p>if a <code>BOOT:</code> section was present in the <em>.xs</em> file, the code there is called.</p>
</li>
</ul>
<p>Consequently, if the code in the <em>.pm</em> file makes calls to these XSUBs, it is
convenient to have XSUBs installed before the Perl code is defined; for
example, this makes prototypes for XSUBs visible to this Perl code.
Alternatively, if the <code>BOOT:</code> section makes calls to Perl functions (or
uses Perl variables) defined in the <em>.pm</em> file, they must be defined prior to
the call to <a href="#item_load"><code>XSLoader::load()</code></a> (or <code>bootstrap()</code>).</p>
<p>The first situation being much more frequent, it makes sense to rewrite the
boilerplate as</p>
<pre>
    <span class="keyword">package</span> <span class="variable">YourPackage</span><span class="operator">;</span>
    <span class="keyword">use</span> <span class="variable">XSLoader</span><span class="operator">;</span>
    <span class="keyword">use</span> <span class="variable">vars</span> <span class="string">qw($VERSION @ISA)</span><span class="operator">;</span>
</pre>
<pre>
    <span class="keyword">BEGIN</span> <span class="operator">{</span>
       <span class="variable">@ISA</span> <span class="operator">=</span> <span class="string">qw( OnePackage OtherPackage )</span><span class="operator">;</span>
       <span class="variable">$VERSION</span> <span class="operator">=</span> <span class="string">'0.01'</span><span class="operator">;</span>
</pre>
<pre>
       <span class="comment"># Put Perl code used in the BOOT: section here</span>
</pre>
<pre>
       <span class="variable">XSLoader::load</span> <span class="string">'YourPackage'</span><span class="operator">,</span> <span class="variable">$VERSION</span><span class="operator">;</span>
           <span class="operator">}</span>
</pre>
<pre>
    <span class="comment"># Put Perl code making calls into XSUBs here</span>
</pre>
<p>
</p>
<h2><a name="the_most_hairy_case">The most hairy case</a></h2>
<p>If the interdependence of your <code>BOOT:</code> section and Perl code is
more complicated than this (e.g., the <code>BOOT:</code> section makes calls to Perl
functions which make calls to XSUBs with prototypes), get rid of the <code>BOOT:</code>
section altogether.  Replace it with a function <code>onBOOT()</code>, and call it like
this:</p>
<pre>
    <span class="keyword">package</span> <span class="variable">YourPackage</span><span class="operator">;</span>
    <span class="keyword">use</span> <span class="variable">XSLoader</span><span class="operator">;</span>
    <span class="keyword">use</span> <span class="variable">vars</span> <span class="string">qw($VERSION @ISA)</span><span class="operator">;</span>
</pre>
<pre>
    <span class="keyword">BEGIN</span> <span class="operator">{</span>
       <span class="variable">@ISA</span> <span class="operator">=</span> <span class="string">qw( OnePackage OtherPackage )</span><span class="operator">;</span>
       <span class="variable">$VERSION</span> <span class="operator">=</span> <span class="string">'0.01'</span><span class="operator">;</span>
       <span class="variable">XSLoader::load</span> <span class="string">'YourPackage'</span><span class="operator">,</span> <span class="variable">$VERSION</span><span class="operator">;</span>
    <span class="operator">}</span>
</pre>
<pre>
    <span class="comment"># Put Perl code used in onBOOT() function here; calls to XSUBs are</span>
    <span class="comment"># prototype-checked.</span>
</pre>
<pre>
    <span class="variable">onBOOT</span><span class="operator">;</span>
</pre>
<pre>
    <span class="comment"># Put Perl initialization code assuming that XS is initialized here</span>
</pre>
<p>
</p>
<hr />
<h1><a name="diagnostics">DIAGNOSTICS</a></h1>
<dl>
<dt><strong><a name="item_can_27t_find__27_25s_27_symbol_in__25s">Can't find '%s' symbol in %s</a></strong>

<dd>
<p><strong>(F)</strong> The bootstrap symbol could not be found in the extension module.</p>
</dd>
</li>
<dt><strong><a name="item_can_27t_load__27_25s_27_for_module__25s_3a__25s">Can't load '%s' for module %s: %s</a></strong>

<dd>
<p><strong>(F)</strong> The loading or initialisation of the extension module failed.
The detailed error follows.</p>
</dd>
</li>
<dt><strong><a name="item_undefined_symbols_present_after_loading__25s_3a__2">Undefined symbols present after loading %s: %s</a></strong>

<dd>
<p><strong>(W)</strong> As the message says, some symbols stay undefined although the
extension module was correctly loaded and initialised. The list of undefined
symbols follows.</p>
</dd>
</li>
<dt><strong><a name="item_load">XSLoader::load('Your::Module', $Your::Module::VERSION)</a></strong>

<dd>
<p><strong>(F)</strong> You tried to invoke <a href="#item_load"><code>load()</code></a> without any argument. You must supply
a module name, and optionally its version.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="limitations">LIMITATIONS</a></h1>
<p>To reduce the overhead as much as possible, only one possible location
is checked to find the extension DLL (this location is where <code>make install</code>
would put the DLL).  If not found, the search for the DLL is transparently
delegated to <code>DynaLoader</code>, which looks for the DLL along the <a href="../lib/Pod/perlvar.html#item__inc"><code>@INC</code></a> list.</p>
<p>In particular, this is applicable to the structure of <a href="../lib/Pod/perlvar.html#item__inc"><code>@INC</code></a> used for testing
not-yet-installed extensions.  This means that running uninstalled extensions
may have much more overhead than running the same extensions after
<code>make install</code>.</p>
<p>
</p>
<hr />
<h1><a name="bugs">BUGS</a></h1>
<p>Please report any bugs or feature requests via the <code>perlbug(1)</code> utility.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><a href="../lib/DynaLoader.html">the DynaLoader manpage</a></p>
<p>
</p>
<hr />
<h1><a name="authors">AUTHORS</a></h1>
<p>Ilya Zakharevich originally extracted <code>XSLoader</code> from <code>DynaLoader</code>.</p>
<p>CPAN version is currently maintained by S&eacute;bastien Aperghis-Tramoni
&lt;<a href="mailto:[e-mail]">[e-mail]</a>&gt;</p>
<p>Previous maintainer was Michael G Schwern &lt;<a href="mailto:[e-mail]">[e-mail]</a>&gt;</p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.</p>

</body>

</html>