| 1 |
=head1 NAME |
| 2 |
|
| 3 |
perlxstut - Tutorial for writing XSUBs |
| 4 |
|
| 5 |
=head1 DESCRIPTION |
| 6 |
|
| 7 |
This tutorial will educate the reader on the steps involved in creating |
| 8 |
a Perl extension. The reader is assumed to have access to L<perlguts>, |
| 9 |
L<perlclib>, L<perlapi>, and L<perlxs>. |
| 10 |
|
| 11 |
This tutorial starts with very simple examples and becomes more complex, |
| 12 |
with each new example adding new features. Certain concepts may not be |
| 13 |
completely explained until later in the tutorial in order to slowly ease |
| 14 |
the reader into building extensions. |
| 15 |
|
| 16 |
This tutorial was written from a Unix point of view. Where I know them |
| 17 |
to be otherwise different for other platforms (e.g. Win32), I will list |
| 18 |
them. If you find something that was missed, please let me know. |
| 19 |
|
| 20 |
=head1 SPECIAL NOTES |
| 21 |
|
| 22 |
=head2 make |
| 23 |
|
| 24 |
This tutorial assumes that the make program that Perl is configured to |
| 25 |
use is called C<make>. Instead of running "make" in the examples that |
| 26 |
follow, you may have to substitute whatever make program Perl has been |
| 27 |
configured to use. Running B<perl -V:make> should tell you what it is. |
| 28 |
|
| 29 |
=head2 Version caveat |
| 30 |
|
| 31 |
When writing a Perl extension for general consumption, one should expect that |
| 32 |
the extension will be used with versions of Perl different from the |
| 33 |
version available on your machine. Since you are reading this document, |
| 34 |
the version of Perl on your machine is probably 5.005 or later, but the users |
| 35 |
of your extension may have more ancient versions. |
| 36 |
|
| 37 |
To understand what kinds of incompatibilities one may expect, and in the rare |
| 38 |
case that the version of Perl on your machine is older than this document, |
| 39 |
see the section on "Troubleshooting these Examples" for more information. |
| 40 |
|
| 41 |
If your extension uses some features of Perl which are not available on older |
| 42 |
releases of Perl, your users would appreciate an early meaningful warning. |
| 43 |
You would probably put this information into the F<README> file, but nowadays |
| 44 |
installation of extensions may be performed automatically, guided by F<CPAN.pm> |
| 45 |
module or other tools. |
| 46 |
|
| 47 |
In MakeMaker-based installations, F<Makefile.PL> provides the earliest |
| 48 |
opportunity to perform version checks. One can put something like this |
| 49 |
in F<Makefile.PL> for this purpose: |
| 50 |
|
| 51 |
eval { require 5.007 } |
| 52 |
or die <<EOD; |
| 53 |
############ |
| 54 |
### This module uses frobnication framework which is not available |
| 55 |
### before version 5.007 of Perl. Upgrade your Perl before |
| 56 |
### installing Kara::Mba. |
| 57 |
############ |
| 58 |
EOD |
| 59 |
|
| 60 |
=head2 Dynamic Loading versus Static Loading |
| 61 |
|
| 62 |
It is commonly thought that if a system does not have the capability to |
| 63 |
dynamically load a library, you cannot build XSUBs. This is incorrect. |
| 64 |
You I<can> build them, but you must link the XSUBs subroutines with the |
| 65 |
rest of Perl, creating a new executable. This situation is similar to |
| 66 |
Perl 4. |
| 67 |
|
| 68 |
This tutorial can still be used on such a system. The XSUB build mechanism |
| 69 |
will check the system and build a dynamically-loadable library if possible, |
| 70 |
or else a static library and then, optionally, a new statically-linked |
| 71 |
executable with that static library linked in. |
| 72 |
|
| 73 |
Should you wish to build a statically-linked executable on a system which |
| 74 |
can dynamically load libraries, you may, in all the following examples, |
| 75 |
where the command "C<make>" with no arguments is executed, run the command |
| 76 |
"C<make perl>" instead. |
| 77 |
|
| 78 |
If you have generated such a statically-linked executable by choice, then |
| 79 |
instead of saying "C<make test>", you should say "C<make test_static>". |
| 80 |
On systems that cannot build dynamically-loadable libraries at all, simply |
| 81 |
saying "C<make test>" is sufficient. |
| 82 |
|
| 83 |
=head2 Threads and PERL_NO_GET_CONTEXT |
| 84 |
|
| 85 |
For threaded builds, perl requires the context pointer for the current |
| 86 |
thread, without C<PERL_NO_GET_CONTEXT>, perl will call a function to |
| 87 |
retrieve the context. |
| 88 |
|
| 89 |
For improved performance, include: |
| 90 |
|
| 91 |
#define PERL_NO_GET_CONTEXT |
| 92 |
|
| 93 |
as shown below. |
| 94 |
|
| 95 |
For more details, see L<perlguts|perlguts/How multiple interpreters |
| 96 |
and concurrency are supported>. |
| 97 |
|
| 98 |
=head1 TUTORIAL |
| 99 |
|
| 100 |
Now let's go on with the show! |
| 101 |
|
| 102 |
=head2 EXAMPLE 1 |
| 103 |
|
| 104 |
Our first extension will be very simple. When we call the routine in the |
| 105 |
extension, it will print out a well-known message and return. |
| 106 |
|
| 107 |
Run "C<h2xs -A -n Mytest>". This creates a directory named Mytest, |
| 108 |
possibly under ext/ if that directory exists in the current working |
| 109 |
directory. Several files will be created under the Mytest dir, including |
| 110 |
MANIFEST, Makefile.PL, lib/Mytest.pm, Mytest.xs, t/Mytest.t, and Changes. |
| 111 |
|
| 112 |
The MANIFEST file contains the names of all the files just created in the |
| 113 |
Mytest directory. |
| 114 |
|
| 115 |
The file Makefile.PL should look something like this: |
| 116 |
|
| 117 |
use ExtUtils::MakeMaker; |
| 118 |
|
| 119 |
# See lib/ExtUtils/MakeMaker.pm for details of how to influence |
| 120 |
# the contents of the Makefile that is written. |
| 121 |
WriteMakefile( |
| 122 |
NAME => 'Mytest', |
| 123 |
VERSION_FROM => 'Mytest.pm', # finds $VERSION |
| 124 |
LIBS => [''], # e.g., '-lm' |
| 125 |
DEFINE => '', # e.g., '-DHAVE_SOMETHING' |
| 126 |
INC => '-I', # e.g., '-I. -I/usr/include/other' |
| 127 |
); |
| 128 |
|
| 129 |
The file Mytest.pm should start with something like this: |
| 130 |
|
| 131 |
package Mytest; |
| 132 |
|
| 133 |
use 5.008008; |
| 134 |
use strict; |
| 135 |
use warnings; |
| 136 |
|
| 137 |
require Exporter; |
| 138 |
|
| 139 |
our @ISA = qw(Exporter); |
| 140 |
our %EXPORT_TAGS = ( 'all' => [ qw( |
| 141 |
|
| 142 |
) ] ); |
| 143 |
|
| 144 |
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); |
| 145 |
|
| 146 |
our @EXPORT = qw( |
| 147 |
|
| 148 |
); |
| 149 |
|
| 150 |
our $VERSION = '0.01'; |
| 151 |
|
| 152 |
require XSLoader; |
| 153 |
XSLoader::load('Mytest', $VERSION); |
| 154 |
|
| 155 |
# Preloaded methods go here. |
| 156 |
|
| 157 |
1; |
| 158 |
__END__ |
| 159 |
# Below is the stub of documentation for your module. You better |
| 160 |
# edit it! |
| 161 |
|
| 162 |
The rest of the .pm file contains sample code for providing documentation for |
| 163 |
the extension. |
| 164 |
|
| 165 |
Finally, the Mytest.xs file should look something like this: |
| 166 |
|
| 167 |
#define PERL_NO_GET_CONTEXT |
| 168 |
#include "EXTERN.h" |
| 169 |
#include "perl.h" |
| 170 |
#include "XSUB.h" |
| 171 |
|
| 172 |
#include "ppport.h" |
| 173 |
|
| 174 |
MODULE = Mytest PACKAGE = Mytest |
| 175 |
|
| 176 |
Let's edit the .xs file by adding this to the end of the file: |
| 177 |
|
| 178 |
void |
| 179 |
hello() |
| 180 |
CODE: |
| 181 |
printf("Hello, world!\n"); |
| 182 |
|
| 183 |
It is okay for the lines starting at the "CODE:" line to not be indented. |
| 184 |
However, for readability purposes, it is suggested that you indent CODE: |
| 185 |
one level and the lines following one more level. |
| 186 |
|
| 187 |
Now we'll run "C<perl Makefile.PL>". This will create a real Makefile, |
| 188 |
which make needs. Its output looks something like: |
| 189 |
|
| 190 |
% perl Makefile.PL |
| 191 |
Checking if your kit is complete... |
| 192 |
Looks good |
| 193 |
Writing Makefile for Mytest |
| 194 |
% |
| 195 |
|
| 196 |
Now, running make will produce output that looks something like this (some |
| 197 |
long lines have been shortened for clarity and some extraneous lines have |
| 198 |
been deleted): |
| 199 |
|
| 200 |
% make |
| 201 |
cp lib/Mytest.pm blib/lib/Mytest.pm |
| 202 |
perl xsubpp -typemap typemap Mytest.xs > Mytest.xsc && \ |
| 203 |
mv Mytest.xsc Mytest.c |
| 204 |
Please specify prototyping behavior for Mytest.xs (see perlxs manual) |
| 205 |
cc -c Mytest.c |
| 206 |
Running Mkbootstrap for Mytest () |
| 207 |
chmod 644 Mytest.bs |
| 208 |
rm -f blib/arch/auto/Mytest/Mytest.so |
| 209 |
cc -shared -L/usr/local/lib Mytest.o -o blib/arch/auto/Mytest/Mytest.so |
| 210 |
|
| 211 |
chmod 755 blib/arch/auto/Mytest/Mytest.so |
| 212 |
cp Mytest.bs blib/arch/auto/Mytest/Mytest.bs |
| 213 |
chmod 644 blib/arch/auto/Mytest/Mytest.bs |
| 214 |
Manifying blib/man3/Mytest.3pm |
| 215 |
% |
| 216 |
|
| 217 |
You can safely ignore the line about "prototyping behavior" - it is |
| 218 |
explained in L<perlxs/"The PROTOTYPES: Keyword">. |
| 219 |
|
| 220 |
Perl has its own special way of easily writing test scripts, but for this |
| 221 |
example only, we'll create our own test script. Create a file called hello |
| 222 |
that looks like this: |
| 223 |
|
| 224 |
#! /opt/perl5/bin/perl |
| 225 |
|
| 226 |
use ExtUtils::testlib; |
| 227 |
|
| 228 |
use Mytest; |
| 229 |
|
| 230 |
Mytest::hello(); |
| 231 |
|
| 232 |
Now we make the script executable (C<chmod +x hello>), run the script |
| 233 |
and we should see the following output: |
| 234 |
|
| 235 |
% ./hello |
| 236 |
Hello, world! |
| 237 |
% |
| 238 |
|
| 239 |
=head2 EXAMPLE 2 |
| 240 |
|
| 241 |
Now let's add to our extension a subroutine that will take a single numeric |
| 242 |
argument as input and return 1 if the number is even or 0 if the number |
| 243 |
is odd. |
| 244 |
|
| 245 |
Add the following to the end of Mytest.xs: |
| 246 |
|
| 247 |
int |
| 248 |
is_even(input) |
| 249 |
int input |
| 250 |
CODE: |
| 251 |
RETVAL = (input % 2 == 0); |
| 252 |
OUTPUT: |
| 253 |
RETVAL |
| 254 |
|
| 255 |
There does not need to be whitespace at the start of the "C<int input>" |
| 256 |
line, but it is useful for improving readability. Placing a semi-colon at |
| 257 |
the end of that line is also optional. Any amount and kind of whitespace |
| 258 |
may be placed between the "C<int>" and "C<input>". |
| 259 |
|
| 260 |
Now re-run make to rebuild our new shared library. |
| 261 |
|
| 262 |
Now perform the same steps as before, generating a Makefile from the |
| 263 |
Makefile.PL file, and running make. |
| 264 |
|
| 265 |
In order to test that our extension works, we now need to look at the |
| 266 |
file Mytest.t. This file is set up to imitate the same kind of testing |
| 267 |
structure that Perl itself has. Within the test script, you perform a |
| 268 |
number of tests to confirm the behavior of the extension, printing "ok" |
| 269 |
when the test is correct, "not ok" when it is not. |
| 270 |
|
| 271 |
use Test::More tests => 4; |
| 272 |
BEGIN { use_ok('Mytest') }; |
| 273 |
|
| 274 |
######################### |
| 275 |
|
| 276 |
# Insert your test code below, the Test::More module is use()ed here |
| 277 |
# so read its man page ( perldoc Test::More ) for help writing this |
| 278 |
# test script. |
| 279 |
|
| 280 |
is( Mytest::is_even(0), 1 ); |
| 281 |
is( Mytest::is_even(1), 0 ); |
| 282 |
is( Mytest::is_even(2), 1 ); |
| 283 |
|
| 284 |
We will be calling the test script through the command "C<make test>". You |
| 285 |
should see output that looks something like this: |
| 286 |
|
| 287 |
%make test |
| 288 |
PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e" |
| 289 |
"test_harness(0, 'blib/lib', 'blib/arch')" t/*.t |
| 290 |
t/Mytest....ok |
| 291 |
All tests successful. |
| 292 |
Files=1, Tests=4, 0 wallclock secs ( 0.03 cusr + 0.00 csys = 0.03 CPU) |
| 293 |
% |
| 294 |
|
| 295 |
=head2 What has gone on? |
| 296 |
|
| 297 |
The program h2xs is the starting point for creating extensions. In later |
| 298 |
examples we'll see how we can use h2xs to read header files and generate |
| 299 |
templates to connect to C routines. |
| 300 |
|
| 301 |
h2xs creates a number of files in the extension directory. The file |
| 302 |
Makefile.PL is a perl script which will generate a true Makefile to build |
| 303 |
the extension. We'll take a closer look at it later. |
| 304 |
|
| 305 |
The .pm and .xs files contain the meat of the extension. The .xs file holds |
| 306 |
the C routines that make up the extension. The .pm file contains routines |
| 307 |
that tell Perl how to load your extension. |
| 308 |
|
| 309 |
Generating the Makefile and running C<make> created a directory called blib |
| 310 |
(which stands for "build library") in the current working directory. This |
| 311 |
directory will contain the shared library that we will build. Once we have |
| 312 |
tested it, we can install it into its final location. |
| 313 |
|
| 314 |
Invoking the test script via "C<make test>" did something very important. |
| 315 |
It invoked perl with all those C<-I> arguments so that it could find the |
| 316 |
various files that are part of the extension. It is I<very> important that |
| 317 |
while you are still testing extensions that you use "C<make test>". If you |
| 318 |
try to run the test script all by itself, you will get a fatal error. |
| 319 |
Another reason it is important to use "C<make test>" to run your test |
| 320 |
script is that if you are testing an upgrade to an already-existing version, |
| 321 |
using "C<make test>" ensures that you will test your new extension, not the |
| 322 |
already-existing version. |
| 323 |
|
| 324 |
When Perl sees a C<use extension;>, it searches for a file with the same name |
| 325 |
as the C<use>'d extension that has a .pm suffix. If that file cannot be found, |
| 326 |
Perl dies with a fatal error. The default search path is contained in the |
| 327 |
C<@INC> array. |
| 328 |
|
| 329 |
In our case, Mytest.pm tells perl that it will need the Exporter and Dynamic |
| 330 |
Loader extensions. It then sets the C<@ISA> and C<@EXPORT> arrays and the |
| 331 |
C<$VERSION> scalar; finally it tells perl to bootstrap the module. Perl |
| 332 |
will call its dynamic loader routine (if there is one) and load the shared |
| 333 |
library. |
| 334 |
|
| 335 |
The two arrays C<@ISA> and C<@EXPORT> are very important. The C<@ISA> |
| 336 |
array contains a list of other packages in which to search for methods (or |
| 337 |
subroutines) that do not exist in the current package. This is usually |
| 338 |
only important for object-oriented extensions (which we will talk about |
| 339 |
much later), and so usually doesn't need to be modified. |
| 340 |
|
| 341 |
The C<@EXPORT> array tells Perl which of the extension's variables and |
| 342 |
subroutines should be placed into the calling package's namespace. Because |
| 343 |
you don't know if the user has already used your variable and subroutine |
| 344 |
names, it's vitally important to carefully select what to export. Do I<not> |
| 345 |
export method or variable names I<by default> without a good reason. |
| 346 |
|
| 347 |
As a general rule, if the module is trying to be object-oriented then don't |
| 348 |
export anything. If it's just a collection of functions and variables, then |
| 349 |
you can export them via another array, called C<@EXPORT_OK>. This array |
| 350 |
does not automatically place its subroutine and variable names into the |
| 351 |
namespace unless the user specifically requests that this be done. |
| 352 |
|
| 353 |
See L<perlmod> for more information. |
| 354 |
|
| 355 |
The C<$VERSION> variable is used to ensure that the .pm file and the shared |
| 356 |
library are "in sync" with each other. Any time you make changes to |
| 357 |
the .pm or .xs files, you should increment the value of this variable. |
| 358 |
|
| 359 |
=head2 Writing good test scripts |
| 360 |
|
| 361 |
The importance of writing good test scripts cannot be over-emphasized. You |
| 362 |
should closely follow the "ok/not ok" style that Perl itself uses, so that |
| 363 |
it is very easy and unambiguous to determine the outcome of each test case. |
| 364 |
When you find and fix a bug, make sure you add a test case for it. |
| 365 |
|
| 366 |
By running "C<make test>", you ensure that your Mytest.t script runs and uses |
| 367 |
the correct version of your extension. If you have many test cases, |
| 368 |
save your test files in the "t" directory and use the suffix ".t". |
| 369 |
When you run "C<make test>", all of these test files will be executed. |
| 370 |
|
| 371 |
=head2 EXAMPLE 3 |
| 372 |
|
| 373 |
Our third extension will take one argument as its input, round off that |
| 374 |
value, and set the I<argument> to the rounded value. |
| 375 |
|
| 376 |
Add the following to the end of Mytest.xs: |
| 377 |
|
| 378 |
void |
| 379 |
round(arg) |
| 380 |
double arg |
| 381 |
CODE: |
| 382 |
if (arg > 0.0) { |
| 383 |
arg = floor(arg + 0.5); |
| 384 |
} else if (arg < 0.0) { |
| 385 |
arg = ceil(arg - 0.5); |
| 386 |
} else { |
| 387 |
arg = 0.0; |
| 388 |
} |
| 389 |
OUTPUT: |
| 390 |
arg |
| 391 |
|
| 392 |
Edit the Makefile.PL file so that the corresponding line looks like this: |
| 393 |
|
| 394 |
LIBS => ['-lm'], # e.g., '-lm' |
| 395 |
|
| 396 |
Generate the Makefile and run make. Change the test number in Mytest.t to |
| 397 |
"9" and add the following tests: |
| 398 |
|
| 399 |
my $i; |
| 400 |
|
| 401 |
$i = -1.5; |
| 402 |
Mytest::round($i); |
| 403 |
is( $i, -2.0, 'Rounding -1.5 to -2.0' ); |
| 404 |
|
| 405 |
$i = -1.1; |
| 406 |
Mytest::round($i); |
| 407 |
is( $i, -1.0, 'Rounding -1.1 to -1.0' ); |
| 408 |
|
| 409 |
$i = 0.0; |
| 410 |
Mytest::round($i); |
| 411 |
is( $i, 0.0, 'Rounding 0.0 to 0.0' ); |
| 412 |
|
| 413 |
$i = 0.5; |
| 414 |
Mytest::round($i); |
| 415 |
is( $i, 1.0, 'Rounding 0.5 to 1.0' ); |
| 416 |
|
| 417 |
$i = 1.2; |
| 418 |
Mytest::round($i); |
| 419 |
is( $i, 1.0, 'Rounding 1.2 to 1.0' ); |
| 420 |
|
| 421 |
Running "C<make test>" should now print out that all nine tests are okay. |
| 422 |
|
| 423 |
Notice that in these new test cases, the argument passed to round was a |
| 424 |
scalar variable. You might be wondering if you can round a constant or |
| 425 |
literal. To see what happens, temporarily add the following line to Mytest.t: |
| 426 |
|
| 427 |
Mytest::round(3); |
| 428 |
|
| 429 |
Run "C<make test>" and notice that Perl dies with a fatal error. Perl won't |
| 430 |
let you change the value of constants! |
| 431 |
|
| 432 |
=head2 What's new here? |
| 433 |
|
| 434 |
=over 4 |
| 435 |
|
| 436 |
=item * |
| 437 |
|
| 438 |
We've made some changes to Makefile.PL. In this case, we've specified an |
| 439 |
extra library to be linked into the extension's shared library, the math |
| 440 |
library libm in this case. We'll talk later about how to write XSUBs that |
| 441 |
can call every routine in a library. |
| 442 |
|
| 443 |
=item * |
| 444 |
|
| 445 |
The value of the function is not being passed back as the function's return |
| 446 |
value, but by changing the value of the variable that was passed into the |
| 447 |
function. You might have guessed that when you saw that the return value |
| 448 |
of round is of type "void". |
| 449 |
|
| 450 |
=back |
| 451 |
|
| 452 |
=head2 Input and Output Parameters |
| 453 |
|
| 454 |
You specify the parameters that will be passed into the XSUB on the line(s) |
| 455 |
after you declare the function's return value and name. Each input parameter |
| 456 |
line starts with optional whitespace, and may have an optional terminating |
| 457 |
semicolon. |
| 458 |
|
| 459 |
The list of output parameters occurs at the very end of the function, just |
| 460 |
after the OUTPUT: directive. The use of RETVAL tells Perl that you |
| 461 |
wish to send this value back as the return value of the XSUB function. In |
| 462 |
Example 3, we wanted the "return value" placed in the original variable |
| 463 |
which we passed in, so we listed it (and not RETVAL) in the OUTPUT: section. |
| 464 |
|
| 465 |
=head2 The XSUBPP Program |
| 466 |
|
| 467 |
The B<xsubpp> program takes the XS code in the .xs file and translates it into |
| 468 |
C code, placing it in a file whose suffix is .c. The C code created makes |
| 469 |
heavy use of the C functions within Perl. |
| 470 |
|
| 471 |
=head2 The TYPEMAP file |
| 472 |
|
| 473 |
The B<xsubpp> program uses rules to convert from Perl's data types (scalar, |
| 474 |
array, etc.) to C's data types (int, char, etc.). These rules are stored |
| 475 |
in the typemap file ($PERLLIB/ExtUtils/typemap). There's a brief discussion |
| 476 |
below, but all the nitty-gritty details can be found in L<perlxstypemap>. |
| 477 |
If you have a new-enough version of perl (5.16 and up) or an upgraded |
| 478 |
XS compiler (C<ExtUtils::ParseXS> 3.13_01 or better), then you can inline |
| 479 |
typemaps in your XS instead of writing separate files. |
| 480 |
Either way, this typemap thing is split into three parts: |
| 481 |
|
| 482 |
The first section maps various C data types to a name, which corresponds |
| 483 |
somewhat with the various Perl types. The second section contains C code |
| 484 |
which B<xsubpp> uses to handle input parameters. The third section contains |
| 485 |
C code which B<xsubpp> uses to handle output parameters. |
| 486 |
|
| 487 |
Let's take a look at a portion of the .c file created for our extension. |
| 488 |
The file name is Mytest.c: |
| 489 |
|
| 490 |
XS(XS_Mytest_round) |
| 491 |
{ |
| 492 |
dXSARGS; |
| 493 |
if (items != 1) |
| 494 |
Perl_croak(aTHX_ "Usage: Mytest::round(arg)"); |
| 495 |
PERL_UNUSED_VAR(cv); /* -W */ |
| 496 |
{ |
| 497 |
double arg = (double)SvNV(ST(0)); /* XXXXX */ |
| 498 |
if (arg > 0.0) { |
| 499 |
arg = floor(arg + 0.5); |
| 500 |
} else if (arg < 0.0) { |
| 501 |
arg = ceil(arg - 0.5); |
| 502 |
} else { |
| 503 |
arg = 0.0; |
| 504 |
} |
| 505 |
sv_setnv(ST(0), (double)arg); /* XXXXX */ |
| 506 |
SvSETMAGIC(ST(0)); |
| 507 |
} |
| 508 |
XSRETURN_EMPTY; |
| 509 |
} |
| 510 |
|
| 511 |
Notice the two lines commented with "XXXXX". If you check the first part |
| 512 |
of the typemap file (or section), you'll see that doubles are of type |
| 513 |
T_DOUBLE. In the INPUT part of the typemap, an argument that is T_DOUBLE |
| 514 |
is assigned to the variable arg by calling the routine SvNV on something, |
| 515 |
then casting it to double, then assigned to the variable arg. Similarly, |
| 516 |
in the OUTPUT section, once arg has its final value, it is passed to the |
| 517 |
sv_setnv function to be passed back to the calling subroutine. These two |
| 518 |
functions are explained in L<perlguts>; we'll talk more later about what |
| 519 |
that "ST(0)" means in the section on the argument stack. |
| 520 |
|
| 521 |
=head2 Warning about Output Arguments |
| 522 |
|
| 523 |
In general, it's not a good idea to write extensions that modify their input |
| 524 |
parameters, as in Example 3. Instead, you should probably return multiple |
| 525 |
values in an array and let the caller handle them (we'll do this in a later |
| 526 |
example). However, in order to better accommodate calling pre-existing C |
| 527 |
routines, which often do modify their input parameters, this behavior is |
| 528 |
tolerated. |
| 529 |
|
| 530 |
=head2 EXAMPLE 4 |
| 531 |
|
| 532 |
In this example, we'll now begin to write XSUBs that will interact with |
| 533 |
pre-defined C libraries. To begin with, we will build a small library of |
| 534 |
our own, then let h2xs write our .pm and .xs files for us. |
| 535 |
|
| 536 |
Create a new directory called Mytest2 at the same level as the directory |
| 537 |
Mytest. In the Mytest2 directory, create another directory called mylib, |
| 538 |
and cd into that directory. |
| 539 |
|
| 540 |
Here we'll create some files that will generate a test library. These will |
| 541 |
include a C source file and a header file. We'll also create a Makefile.PL |
| 542 |
in this directory. Then we'll make sure that running make at the Mytest2 |
| 543 |
level will automatically run this Makefile.PL file and the resulting Makefile. |
| 544 |
|
| 545 |
In the mylib directory, create a file mylib.h that looks like this: |
| 546 |
|
| 547 |
#define TESTVAL 4 |
| 548 |
|
| 549 |
extern double foo(int, long, const char*); |
| 550 |
|
| 551 |
Also create a file mylib.c that looks like this: |
| 552 |
|
| 553 |
#include <stdlib.h> |
| 554 |
#include "mylib.h" |
| 555 |
|
| 556 |
double |
| 557 |
foo(int a, long b, const char *c) |
| 558 |
{ |
| 559 |
return (a + b + atof(c) + TESTVAL); |
| 560 |
} |
| 561 |
|
| 562 |
And finally create a file Makefile.PL that looks like this: |
| 563 |
|
| 564 |
use ExtUtils::MakeMaker; |
| 565 |
$Verbose = 1; |
| 566 |
WriteMakefile( |
| 567 |
NAME => 'Mytest2::mylib', |
| 568 |
SKIP => [qw(all static static_lib dynamic dynamic_lib)], |
| 569 |
clean => {'FILES' => 'libmylib$(LIB_EXT)'}, |
| 570 |
); |
| 571 |
|
| 572 |
|
| 573 |
sub MY::top_targets { |
| 574 |
' |
| 575 |
all :: static |
| 576 |
|
| 577 |
pure_all :: static |
| 578 |
|
| 579 |
static :: libmylib$(LIB_EXT) |
| 580 |
|
| 581 |
libmylib$(LIB_EXT): $(O_FILES) |
| 582 |
$(AR) cr libmylib$(LIB_EXT) $(O_FILES) |
| 583 |
$(RANLIB) libmylib$(LIB_EXT) |
| 584 |
|
| 585 |
'; |
| 586 |
} |
| 587 |
|
| 588 |
Make sure you use a tab and not spaces on the lines beginning with "$(AR)" |
| 589 |
and "$(RANLIB)". Make will not function properly if you use spaces. |
| 590 |
It has also been reported that the "cr" argument to $(AR) is unnecessary |
| 591 |
on Win32 systems. |
| 592 |
|
| 593 |
We will now create the main top-level Mytest2 files. Change to the directory |
| 594 |
above Mytest2 and run the following command: |
| 595 |
|
| 596 |
% h2xs -O -n Mytest2 Mytest2/mylib/mylib.h |
| 597 |
|
| 598 |
This will print out a warning about overwriting Mytest2, but that's okay. |
| 599 |
Our files are stored in Mytest2/mylib, and will be untouched. |
| 600 |
|
| 601 |
The normal Makefile.PL that h2xs generates doesn't know about the mylib |
| 602 |
directory. We need to tell it that there is a subdirectory and that we |
| 603 |
will be generating a library in it. Let's add the argument MYEXTLIB to |
| 604 |
the WriteMakefile call so that it looks like this: |
| 605 |
|
| 606 |
WriteMakefile( |
| 607 |
NAME => 'Mytest2', |
| 608 |
VERSION_FROM => 'Mytest2.pm', # finds $VERSION |
| 609 |
LIBS => [''], # e.g., '-lm' |
| 610 |
DEFINE => '', # e.g., '-DHAVE_SOMETHING' |
| 611 |
INC => '', # e.g., '-I/usr/include/other' |
| 612 |
MYEXTLIB => 'mylib/libmylib$(LIB_EXT)', |
| 613 |
); |
| 614 |
|
| 615 |
and then at the end add a subroutine (which will override the pre-existing |
| 616 |
subroutine). Remember to use a tab character to indent the line beginning |
| 617 |
with "cd"! |
| 618 |
|
| 619 |
sub MY::postamble { |
| 620 |
' |
| 621 |
$(MYEXTLIB): mylib/Makefile |
| 622 |
cd mylib && $(MAKE) $(PASSTHRU) |
| 623 |
'; |
| 624 |
} |
| 625 |
|
| 626 |
Let's also fix the MANIFEST file by appending the following three lines: |
| 627 |
|
| 628 |
mylib/Makefile.PL |
| 629 |
mylib/mylib.c |
| 630 |
mylib/mylib.h |
| 631 |
|
| 632 |
To keep our namespace nice and unpolluted, edit the .pm file and change |
| 633 |
the variable C<@EXPORT> to C<@EXPORT_OK>. Finally, in the |
| 634 |
.xs file, edit the #include line to read: |
| 635 |
|
| 636 |
#include "mylib/mylib.h" |
| 637 |
|
| 638 |
And also add the following function definition to the end of the .xs file: |
| 639 |
|
| 640 |
double |
| 641 |
foo(a,b,c) |
| 642 |
int a |
| 643 |
long b |
| 644 |
const char * c |
| 645 |
OUTPUT: |
| 646 |
RETVAL |
| 647 |
|
| 648 |
Now we also need to create a typemap because the default Perl doesn't |
| 649 |
currently support the C<const char *> type. Include a new TYPEMAP |
| 650 |
section in your XS code before the above function: |
| 651 |
|
| 652 |
TYPEMAP: <<END |
| 653 |
const char * T_PV |
| 654 |
END |
| 655 |
|
| 656 |
Now run perl on the top-level Makefile.PL. Notice that it also created a |
| 657 |
Makefile in the mylib directory. Run make and watch that it does cd into |
| 658 |
the mylib directory and run make in there as well. |
| 659 |
|
| 660 |
Now edit the Mytest2.t script and change the number of tests to "5", |
| 661 |
and add the following lines to the end of the script: |
| 662 |
|
| 663 |
is( Mytest2::foo( 1, 2, "Hello, world!" ), 7 ); |
| 664 |
is( Mytest2::foo( 1, 2, "0.0" ), 7 ); |
| 665 |
ok( abs( Mytest2::foo( 0, 0, "-3.4" ) - 0.6 ) <= 0.01 ); |
| 666 |
|
| 667 |
(When dealing with floating-point comparisons, it is best to not check for |
| 668 |
equality, but rather that the difference between the expected and actual |
| 669 |
result is below a certain amount (called epsilon) which is 0.01 in this case) |
| 670 |
|
| 671 |
Run "C<make test>" and all should be well. There are some warnings on missing |
| 672 |
tests for the Mytest2::mylib extension, but you can ignore them. |
| 673 |
|
| 674 |
=head2 What has happened here? |
| 675 |
|
| 676 |
Unlike previous examples, we've now run h2xs on a real include file. This |
| 677 |
has caused some extra goodies to appear in both the .pm and .xs files. |
| 678 |
|
| 679 |
=over 4 |
| 680 |
|
| 681 |
=item * |
| 682 |
|
| 683 |
In the .xs file, there's now a #include directive with the absolute path to |
| 684 |
the mylib.h header file. We changed this to a relative path so that we |
| 685 |
could move the extension directory if we wanted to. |
| 686 |
|
| 687 |
=item * |
| 688 |
|
| 689 |
There's now some new C code that's been added to the .xs file. The purpose |
| 690 |
of the C<constant> routine is to make the values that are #define'd in the |
| 691 |
header file accessible by the Perl script (by calling either C<TESTVAL> or |
| 692 |
C<&Mytest2::TESTVAL>). There's also some XS code to allow calls to the |
| 693 |
C<constant> routine. |
| 694 |
|
| 695 |
=item * |
| 696 |
|
| 697 |
The .pm file originally exported the name C<TESTVAL> in the C<@EXPORT> array. |
| 698 |
This could lead to name clashes. A good rule of thumb is that if the #define |
| 699 |
is only going to be used by the C routines themselves, and not by the user, |
| 700 |
they should be removed from the C<@EXPORT> array. Alternately, if you don't |
| 701 |
mind using the "fully qualified name" of a variable, you could move most |
| 702 |
or all of the items from the C<@EXPORT> array into the C<@EXPORT_OK> array. |
| 703 |
|
| 704 |
=item * |
| 705 |
|
| 706 |
If our include file had contained #include directives, these would not have |
| 707 |
been processed by h2xs. There is no good solution to this right now. |
| 708 |
|
| 709 |
=item * |
| 710 |
|
| 711 |
We've also told Perl about the library that we built in the mylib |
| 712 |
subdirectory. That required only the addition of the C<MYEXTLIB> variable |
| 713 |
to the WriteMakefile call and the replacement of the postamble subroutine |
| 714 |
to cd into the subdirectory and run make. The Makefile.PL for the |
| 715 |
library is a bit more complicated, but not excessively so. Again we |
| 716 |
replaced the postamble subroutine to insert our own code. This code |
| 717 |
simply specified that the library to be created here was a static archive |
| 718 |
library (as opposed to a dynamically loadable library) and provided the |
| 719 |
commands to build it. |
| 720 |
|
| 721 |
=back |
| 722 |
|
| 723 |
=head2 Anatomy of .xs file |
| 724 |
|
| 725 |
The .xs file of L</EXAMPLE 4> contained some new elements. To understand |
| 726 |
the meaning of these elements, pay attention to the line which reads |
| 727 |
|
| 728 |
MODULE = Mytest2 PACKAGE = Mytest2 |
| 729 |
|
| 730 |
Anything before this line is plain C code which describes which headers |
| 731 |
to include, and defines some convenience functions. No translations are |
| 732 |
performed on this part, apart from having embedded POD documentation |
| 733 |
skipped over (see L<perlpod>) it goes into the generated output C file as is. |
| 734 |
|
| 735 |
Anything after this line is the description of XSUB functions. |
| 736 |
These descriptions are translated by B<xsubpp> into C code which |
| 737 |
implements these functions using Perl calling conventions, and which |
| 738 |
makes these functions visible from Perl interpreter. |
| 739 |
|
| 740 |
Pay a special attention to the function C<constant>. This name appears |
| 741 |
twice in the generated .xs file: once in the first part, as a static C |
| 742 |
function, then another time in the second part, when an XSUB interface to |
| 743 |
this static C function is defined. |
| 744 |
|
| 745 |
This is quite typical for .xs files: usually the .xs file provides |
| 746 |
an interface to an existing C function. Then this C function is defined |
| 747 |
somewhere (either in an external library, or in the first part of .xs file), |
| 748 |
and a Perl interface to this function (i.e. "Perl glue") is described in the |
| 749 |
second part of .xs file. The situation in L<"EXAMPLE 1">, L<"EXAMPLE 2">, |
| 750 |
and L<"EXAMPLE 3">, when all the work is done inside the "Perl glue", is |
| 751 |
somewhat of an exception rather than the rule. |
| 752 |
|
| 753 |
=head2 Getting the fat out of XSUBs |
| 754 |
|
| 755 |
In L</EXAMPLE 4> the second part of .xs file contained the following |
| 756 |
description of an XSUB: |
| 757 |
|
| 758 |
double |
| 759 |
foo(a,b,c) |
| 760 |
int a |
| 761 |
long b |
| 762 |
const char * c |
| 763 |
OUTPUT: |
| 764 |
RETVAL |
| 765 |
|
| 766 |
Note that in contrast with L<"EXAMPLE 1">, L<"EXAMPLE 2"> and L<"EXAMPLE 3">, |
| 767 |
this description does not contain the actual I<code> for what is done |
| 768 |
during a call to Perl function foo(). To understand what is going |
| 769 |
on here, one can add a CODE section to this XSUB: |
| 770 |
|
| 771 |
double |
| 772 |
foo(a,b,c) |
| 773 |
int a |
| 774 |
long b |
| 775 |
const char * c |
| 776 |
CODE: |
| 777 |
RETVAL = foo(a,b,c); |
| 778 |
OUTPUT: |
| 779 |
RETVAL |
| 780 |
|
| 781 |
However, these two XSUBs provide almost identical generated C code: B<xsubpp> |
| 782 |
compiler is smart enough to figure out the C<CODE:> section from the first |
| 783 |
two lines of the description of XSUB. What about C<OUTPUT:> section? In |
| 784 |
fact, that is absolutely the same! The C<OUTPUT:> section can be removed |
| 785 |
as well, I<as far as C<CODE:> section or C<PPCODE:> section> is not |
| 786 |
specified: B<xsubpp> can see that it needs to generate a function call |
| 787 |
section, and will autogenerate the OUTPUT section too. Thus one can |
| 788 |
shortcut the XSUB to become: |
| 789 |
|
| 790 |
double |
| 791 |
foo(a,b,c) |
| 792 |
int a |
| 793 |
long b |
| 794 |
const char * c |
| 795 |
|
| 796 |
Can we do the same with an XSUB |
| 797 |
|
| 798 |
int |
| 799 |
is_even(input) |
| 800 |
int input |
| 801 |
CODE: |
| 802 |
RETVAL = (input % 2 == 0); |
| 803 |
OUTPUT: |
| 804 |
RETVAL |
| 805 |
|
| 806 |
of L<"EXAMPLE 2">? To do this, one needs to define a C function C<int |
| 807 |
is_even(int input)>. As we saw in L<Anatomy of .xs file>, a proper place |
| 808 |
for this definition is in the first part of .xs file. In fact a C function |
| 809 |
|
| 810 |
int |
| 811 |
is_even(int arg) |
| 812 |
{ |
| 813 |
return (arg % 2 == 0); |
| 814 |
} |
| 815 |
|
| 816 |
is probably overkill for this. Something as simple as a C<#define> will |
| 817 |
do too: |
| 818 |
|
| 819 |
#define is_even(arg) ((arg) % 2 == 0) |
| 820 |
|
| 821 |
After having this in the first part of .xs file, the "Perl glue" part becomes |
| 822 |
as simple as |
| 823 |
|
| 824 |
int |
| 825 |
is_even(input) |
| 826 |
int input |
| 827 |
|
| 828 |
This technique of separation of the glue part from the workhorse part has |
| 829 |
obvious tradeoffs: if you want to change a Perl interface, you need to |
| 830 |
change two places in your code. However, it removes a lot of clutter, |
| 831 |
and makes the workhorse part independent from idiosyncrasies of Perl calling |
| 832 |
convention. (In fact, there is nothing Perl-specific in the above description, |
| 833 |
a different version of B<xsubpp> might have translated this to TCL glue or |
| 834 |
Python glue as well.) |
| 835 |
|
| 836 |
=head2 More about XSUB arguments |
| 837 |
|
| 838 |
With the completion of Example 4, we now have an easy way to simulate some |
| 839 |
real-life libraries whose interfaces may not be the cleanest in the world. |
| 840 |
We shall now continue with a discussion of the arguments passed to the |
| 841 |
B<xsubpp> compiler. |
| 842 |
|
| 843 |
When you specify arguments to routines in the .xs file, you are really |
| 844 |
passing three pieces of information for each argument listed. The first |
| 845 |
piece is the order of that argument relative to the others (first, second, |
| 846 |
etc). The second is the type of argument, and consists of the type |
| 847 |
declaration of the argument (e.g., int, char*, etc). The third piece is |
| 848 |
the calling convention for the argument in the call to the library function. |
| 849 |
|
| 850 |
While Perl passes arguments to functions by reference, |
| 851 |
C passes arguments by value; to implement a C function which modifies data |
| 852 |
of one of the "arguments", the actual argument of this C function would be |
| 853 |
a pointer to the data. Thus two C functions with declarations |
| 854 |
|
| 855 |
int string_length(char *s); |
| 856 |
int upper_case_char(char *cp); |
| 857 |
|
| 858 |
may have completely different semantics: the first one may inspect an array |
| 859 |
of chars pointed by s, and the second one may immediately dereference C<cp> |
| 860 |
and manipulate C<*cp> only (using the return value as, say, a success |
| 861 |
indicator). From Perl one would use these functions in |
| 862 |
a completely different manner. |
| 863 |
|
| 864 |
One conveys this info to B<xsubpp> by replacing C<*> before the |
| 865 |
argument by C<&>. C<&> means that the argument should be passed to a library |
| 866 |
function by its address. The above two function may be XSUB-ified as |
| 867 |
|
| 868 |
int |
| 869 |
string_length(s) |
| 870 |
char * s |
| 871 |
|
| 872 |
int |
| 873 |
upper_case_char(cp) |
| 874 |
char &cp |
| 875 |
|
| 876 |
For example, consider: |
| 877 |
|
| 878 |
int |
| 879 |
foo(a,b) |
| 880 |
char &a |
| 881 |
char * b |
| 882 |
|
| 883 |
The first Perl argument to this function would be treated as a char and |
| 884 |
assigned to the variable a, and its address would be passed into the function |
| 885 |
foo. The second Perl argument would be treated as a string pointer and assigned |
| 886 |
to the variable b. The I<value> of b would be passed into the function foo. |
| 887 |
The actual call to the function foo that B<xsubpp> generates would look like |
| 888 |
this: |
| 889 |
|
| 890 |
foo(&a, b); |
| 891 |
|
| 892 |
B<xsubpp> will parse the following function argument lists identically: |
| 893 |
|
| 894 |
char &a |
| 895 |
char&a |
| 896 |
char & a |
| 897 |
|
| 898 |
However, to help ease understanding, it is suggested that you place a "&" |
| 899 |
next to the variable name and away from the variable type), and place a |
| 900 |
"*" near the variable type, but away from the variable name (as in the |
| 901 |
call to foo above). By doing so, it is easy to understand exactly what |
| 902 |
will be passed to the C function; it will be whatever is in the "last |
| 903 |
column". |
| 904 |
|
| 905 |
You should take great pains to try to pass the function the type of variable |
| 906 |
it wants, when possible. It will save you a lot of trouble in the long run. |
| 907 |
|
| 908 |
=head2 The Argument Stack |
| 909 |
|
| 910 |
If we look at any of the C code generated by any of the examples except |
| 911 |
example 1, you will notice a number of references to ST(n), where n is |
| 912 |
usually 0. "ST" is actually a macro that points to the n'th argument |
| 913 |
on the argument stack. ST(0) is thus the first argument on the stack and |
| 914 |
therefore the first argument passed to the XSUB, ST(1) is the second |
| 915 |
argument, and so on. |
| 916 |
|
| 917 |
When you list the arguments to the XSUB in the .xs file, that tells B<xsubpp> |
| 918 |
which argument corresponds to which of the argument stack (i.e., the first |
| 919 |
one listed is the first argument, and so on). You invite disaster if you |
| 920 |
do not list them in the same order as the function expects them. |
| 921 |
|
| 922 |
The actual values on the argument stack are pointers to the values passed |
| 923 |
in. When an argument is listed as being an OUTPUT value, its corresponding |
| 924 |
value on the stack (i.e., ST(0) if it was the first argument) is changed. |
| 925 |
You can verify this by looking at the C code generated for Example 3. |
| 926 |
The code for the round() XSUB routine contains lines that look like this: |
| 927 |
|
| 928 |
double arg = (double)SvNV(ST(0)); |
| 929 |
/* Round the contents of the variable arg */ |
| 930 |
sv_setnv(ST(0), (double)arg); |
| 931 |
|
| 932 |
The arg variable is initially set by taking the value from ST(0), then is |
| 933 |
stored back into ST(0) at the end of the routine. |
| 934 |
|
| 935 |
XSUBs are also allowed to return lists, not just scalars. This must be |
| 936 |
done by manipulating stack values ST(0), ST(1), etc, in a subtly |
| 937 |
different way. See L<perlxs> for details. |
| 938 |
|
| 939 |
XSUBs are also allowed to avoid automatic conversion of Perl function arguments |
| 940 |
to C function arguments. See L<perlxs> for details. Some people prefer |
| 941 |
manual conversion by inspecting C<ST(i)> even in the cases when automatic |
| 942 |
conversion will do, arguing that this makes the logic of an XSUB call clearer. |
| 943 |
Compare with L<"Getting the fat out of XSUBs"> for a similar tradeoff of |
| 944 |
a complete separation of "Perl glue" and "workhorse" parts of an XSUB. |
| 945 |
|
| 946 |
While experts may argue about these idioms, a novice to Perl guts may |
| 947 |
prefer a way which is as little Perl-guts-specific as possible, meaning |
| 948 |
automatic conversion and automatic call generation, as in |
| 949 |
L<"Getting the fat out of XSUBs">. This approach has the additional |
| 950 |
benefit of protecting the XSUB writer from future changes to the Perl API. |
| 951 |
|
| 952 |
=head2 Extending your Extension |
| 953 |
|
| 954 |
Sometimes you might want to provide some extra methods or subroutines |
| 955 |
to assist in making the interface between Perl and your extension simpler |
| 956 |
or easier to understand. These routines should live in the .pm file. |
| 957 |
Whether they are automatically loaded when the extension itself is loaded |
| 958 |
or only loaded when called depends on where in the .pm file the subroutine |
| 959 |
definition is placed. You can also consult L<AutoLoader> for an alternate |
| 960 |
way to store and load your extra subroutines. |
| 961 |
|
| 962 |
=head2 Documenting your Extension |
| 963 |
|
| 964 |
There is absolutely no excuse for not documenting your extension. |
| 965 |
Documentation belongs in the .pm file. This file will be fed to pod2man, |
| 966 |
and the embedded documentation will be converted to the manpage format, |
| 967 |
then placed in the blib directory. It will be copied to Perl's |
| 968 |
manpage directory when the extension is installed. |
| 969 |
|
| 970 |
You may intersperse documentation and Perl code within the .pm file. |
| 971 |
In fact, if you want to use method autoloading, you must do this, |
| 972 |
as the comment inside the .pm file explains. |
| 973 |
|
| 974 |
See L<perlpod> for more information about the pod format. |
| 975 |
|
| 976 |
=head2 Installing your Extension |
| 977 |
|
| 978 |
Once your extension is complete and passes all its tests, installing it |
| 979 |
is quite simple: you simply run "make install". You will either need |
| 980 |
to have write permission into the directories where Perl is installed, |
| 981 |
or ask your system administrator to run the make for you. |
| 982 |
|
| 983 |
Alternately, you can specify the exact directory to place the extension's |
| 984 |
files by placing a "PREFIX=/destination/directory" after the make install |
| 985 |
(or in between the make and install if you have a brain-dead version of make). |
| 986 |
This can be very useful if you are building an extension that will eventually |
| 987 |
be distributed to multiple systems. You can then just archive the files in |
| 988 |
the destination directory and distribute them to your destination systems. |
| 989 |
|
| 990 |
=head2 EXAMPLE 5 |
| 991 |
|
| 992 |
In this example, we'll do some more work with the argument stack. The |
| 993 |
previous examples have all returned only a single value. We'll now |
| 994 |
create an extension that returns an array. |
| 995 |
|
| 996 |
This extension is very Unix-oriented (struct statfs and the statfs system |
| 997 |
call). If you are not running on a Unix system, you can substitute for |
| 998 |
statfs any other function that returns multiple values, you can hard-code |
| 999 |
values to be returned to the caller (although this will be a bit harder |
| 1000 |
to test the error case), or you can simply not do this example. If you |
| 1001 |
change the XSUB, be sure to fix the test cases to match the changes. |
| 1002 |
|
| 1003 |
Return to the Mytest directory and add the following code to the end of |
| 1004 |
Mytest.xs: |
| 1005 |
|
| 1006 |
void |
| 1007 |
statfs(path) |
| 1008 |
char * path |
| 1009 |
INIT: |
| 1010 |
int i; |
| 1011 |
struct statfs buf; |
| 1012 |
|
| 1013 |
PPCODE: |
| 1014 |
i = statfs(path, &buf); |
| 1015 |
if (i == 0) { |
| 1016 |
XPUSHs(sv_2mortal(newSVnv(buf.f_bavail))); |
| 1017 |
XPUSHs(sv_2mortal(newSVnv(buf.f_bfree))); |
| 1018 |
XPUSHs(sv_2mortal(newSVnv(buf.f_blocks))); |
| 1019 |
XPUSHs(sv_2mortal(newSVnv(buf.f_bsize))); |
| 1020 |
XPUSHs(sv_2mortal(newSVnv(buf.f_ffree))); |
| 1021 |
XPUSHs(sv_2mortal(newSVnv(buf.f_files))); |
| 1022 |
XPUSHs(sv_2mortal(newSVnv(buf.f_type))); |
| 1023 |
} else { |
| 1024 |
XPUSHs(sv_2mortal(newSVnv(errno))); |
| 1025 |
} |
| 1026 |
|
| 1027 |
You'll also need to add the following code to the top of the .xs file, just |
| 1028 |
after the include of "XSUB.h": |
| 1029 |
|
| 1030 |
#include <sys/vfs.h> |
| 1031 |
|
| 1032 |
Also add the following code segment to Mytest.t while incrementing the "9" |
| 1033 |
tests to "11": |
| 1034 |
|
| 1035 |
my @a; |
| 1036 |
|
| 1037 |
@a = Mytest::statfs("/blech"); |
| 1038 |
ok( scalar(@a) == 1 && $a[0] == 2 ); |
| 1039 |
|
| 1040 |
@a = Mytest::statfs("/"); |
| 1041 |
is( scalar(@a), 7 ); |
| 1042 |
|
| 1043 |
=head2 New Things in this Example |
| 1044 |
|
| 1045 |
This example added quite a few new concepts. We'll take them one at a time. |
| 1046 |
|
| 1047 |
=over 4 |
| 1048 |
|
| 1049 |
=item * |
| 1050 |
|
| 1051 |
The INIT: directive contains code that will be placed immediately after |
| 1052 |
the argument stack is decoded. C does not allow variable declarations at |
| 1053 |
arbitrary locations inside a function, |
| 1054 |
so this is usually the best way to declare local variables needed by the XSUB. |
| 1055 |
(Alternatively, one could put the whole C<PPCODE:> section into braces, and |
| 1056 |
put these declarations on top.) |
| 1057 |
|
| 1058 |
=item * |
| 1059 |
|
| 1060 |
This routine also returns a different number of arguments depending on the |
| 1061 |
success or failure of the call to statfs. If there is an error, the error |
| 1062 |
number is returned as a single-element array. If the call is successful, |
| 1063 |
then a 7-element array is returned. Since only one argument is passed into |
| 1064 |
this function, we need room on the stack to hold the 7 values which may be |
| 1065 |
returned. |
| 1066 |
|
| 1067 |
We do this by using the PPCODE: directive, rather than the CODE: directive. |
| 1068 |
This tells B<xsubpp> that we will be managing the return values that will be |
| 1069 |
put on the argument stack by ourselves. |
| 1070 |
|
| 1071 |
=item * |
| 1072 |
|
| 1073 |
When we want to place values to be returned to the caller onto the stack, |
| 1074 |
we use the series of macros that begin with "XPUSH". There are five |
| 1075 |
different versions, for placing integers, unsigned integers, doubles, |
| 1076 |
strings, and Perl scalars on the stack. In our example, we placed a |
| 1077 |
Perl scalar onto the stack. (In fact this is the only macro which |
| 1078 |
can be used to return multiple values.) |
| 1079 |
|
| 1080 |
The XPUSH* macros will automatically extend the return stack to prevent |
| 1081 |
it from being overrun. You push values onto the stack in the order you |
| 1082 |
want them seen by the calling program. |
| 1083 |
|
| 1084 |
=item * |
| 1085 |
|
| 1086 |
The values pushed onto the return stack of the XSUB are actually mortal SV's. |
| 1087 |
They are made mortal so that once the values are copied by the calling |
| 1088 |
program, the SV's that held the returned values can be deallocated. |
| 1089 |
If they were not mortal, then they would continue to exist after the XSUB |
| 1090 |
routine returned, but would not be accessible. This is a memory leak. |
| 1091 |
|
| 1092 |
=item * |
| 1093 |
|
| 1094 |
If we were interested in performance, not in code compactness, in the success |
| 1095 |
branch we would not use C<XPUSHs> macros, but C<PUSHs> macros, and would |
| 1096 |
pre-extend the stack before pushing the return values: |
| 1097 |
|
| 1098 |
EXTEND(SP, 7); |
| 1099 |
|
| 1100 |
The tradeoff is that one needs to calculate the number of return values |
| 1101 |
in advance (though overextending the stack will not typically hurt |
| 1102 |
anything but memory consumption). |
| 1103 |
|
| 1104 |
Similarly, in the failure branch we could use C<PUSHs> I<without> extending |
| 1105 |
the stack: the Perl function reference comes to an XSUB on the stack, thus |
| 1106 |
the stack is I<always> large enough to take one return value. |
| 1107 |
|
| 1108 |
=back |
| 1109 |
|
| 1110 |
=head2 EXAMPLE 6 |
| 1111 |
|
| 1112 |
In this example, we will accept a reference to an array as an input |
| 1113 |
parameter, and return a reference to an array of hashes. This will |
| 1114 |
demonstrate manipulation of complex Perl data types from an XSUB. |
| 1115 |
|
| 1116 |
This extension is somewhat contrived. It is based on the code in |
| 1117 |
the previous example. It calls the statfs function multiple times, |
| 1118 |
accepting a reference to an array of filenames as input, and returning |
| 1119 |
a reference to an array of hashes containing the data for each of the |
| 1120 |
filesystems. |
| 1121 |
|
| 1122 |
Return to the Mytest directory and add the following code to the end of |
| 1123 |
Mytest.xs: |
| 1124 |
|
| 1125 |
SV * |
| 1126 |
multi_statfs(paths) |
| 1127 |
SV * paths |
| 1128 |
INIT: |
| 1129 |
AV * results; |
| 1130 |
SSize_t numpaths = 0, n; |
| 1131 |
int i; |
| 1132 |
struct statfs buf; |
| 1133 |
|
| 1134 |
SvGETMAGIC(paths); |
| 1135 |
if ((!SvROK(paths)) |
| 1136 |
|| (SvTYPE(SvRV(paths)) != SVt_PVAV) |
| 1137 |
|| ((numpaths = av_top_index((AV *)SvRV(paths))) < 0)) |
| 1138 |
{ |
| 1139 |
XSRETURN_UNDEF; |
| 1140 |
} |
| 1141 |
results = (AV *)sv_2mortal((SV *)newAV()); |
| 1142 |
CODE: |
| 1143 |
for (n = 0; n <= numpaths; n++) { |
| 1144 |
HV * rh; |
| 1145 |
STRLEN l; |
| 1146 |
SV * path = *av_fetch((AV *)SvRV(paths), n, 0); |
| 1147 |
char * fn = SvPVbyte(path, l); |
| 1148 |
|
| 1149 |
i = statfs(fn, &buf); |
| 1150 |
if (i != 0) { |
| 1151 |
av_push(results, newSVnv(errno)); |
| 1152 |
continue; |
| 1153 |
} |
| 1154 |
|
| 1155 |
rh = (HV *)sv_2mortal((SV *)newHV()); |
| 1156 |
|
| 1157 |
hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0); |
| 1158 |
hv_store(rh, "f_bfree", 7, newSVnv(buf.f_bfree), 0); |
| 1159 |
hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0); |
| 1160 |
hv_store(rh, "f_bsize", 7, newSVnv(buf.f_bsize), 0); |
| 1161 |
hv_store(rh, "f_ffree", 7, newSVnv(buf.f_ffree), 0); |
| 1162 |
hv_store(rh, "f_files", 7, newSVnv(buf.f_files), 0); |
| 1163 |
hv_store(rh, "f_type", 6, newSVnv(buf.f_type), 0); |
| 1164 |
|
| 1165 |
av_push(results, newRV_inc((SV *)rh)); |
| 1166 |
} |
| 1167 |
RETVAL = newRV_inc((SV *)results); |
| 1168 |
OUTPUT: |
| 1169 |
RETVAL |
| 1170 |
|
| 1171 |
And add the following code to Mytest.t, while incrementing the "11" |
| 1172 |
tests to "13": |
| 1173 |
|
| 1174 |
my $results = Mytest::multi_statfs([ '/', '/blech' ]); |
| 1175 |
ok( ref $results->[0] ); |
| 1176 |
ok( ! ref $results->[1] ); |
| 1177 |
|
| 1178 |
=head2 New Things in this Example |
| 1179 |
|
| 1180 |
There are a number of new concepts introduced here, described below: |
| 1181 |
|
| 1182 |
=over 4 |
| 1183 |
|
| 1184 |
=item * |
| 1185 |
|
| 1186 |
This function does not use a typemap. Instead, we declare it as accepting |
| 1187 |
one SV* (scalar) parameter, and returning an SV* value, and we take care of |
| 1188 |
populating these scalars within the code. Because we are only returning |
| 1189 |
one value, we don't need a C<PPCODE:> directive - instead, we use C<CODE:> |
| 1190 |
and C<OUTPUT:> directives. |
| 1191 |
|
| 1192 |
=item * |
| 1193 |
|
| 1194 |
When dealing with references, it is important to handle them with caution. |
| 1195 |
The C<INIT:> block first calls SvGETMAGIC(paths), in case |
| 1196 |
paths is a tied variable. Then it checks that C<SvROK> returns |
| 1197 |
true, which indicates that paths is a valid reference. (Simply |
| 1198 |
checking C<SvROK> won't trigger FETCH on a tied variable.) It |
| 1199 |
then verifies that the object referenced by paths is an array, using C<SvRV> |
| 1200 |
to dereference paths, and C<SvTYPE> to discover its type. As an added test, |
| 1201 |
it checks that the array referenced by paths is non-empty, using the |
| 1202 |
C<av_top_index> function (which returns -1 if the array is empty). The |
| 1203 |
XSRETURN_UNDEF macro is used to abort the XSUB and return the undefined value |
| 1204 |
whenever all three of these conditions are not met. |
| 1205 |
|
| 1206 |
=item * |
| 1207 |
|
| 1208 |
We manipulate several arrays in this XSUB. Note that an array is represented |
| 1209 |
internally by an AV* pointer. The functions and macros for manipulating |
| 1210 |
arrays are similar to the functions in Perl: C<av_top_index> returns the |
| 1211 |
highest index in an AV*, much like $#array; C<av_fetch> fetches a single scalar |
| 1212 |
value from an array, given its index; C<av_push> pushes a scalar value onto the |
| 1213 |
end of the array, automatically extending the array as necessary. |
| 1214 |
|
| 1215 |
Specifically, we read pathnames one at a time from the input array, and |
| 1216 |
store the results in an output array (results) in the same order. If |
| 1217 |
statfs fails, the element pushed onto the return array is the value of |
| 1218 |
errno after the failure. If statfs succeeds, though, the value pushed |
| 1219 |
onto the return array is a reference to a hash containing some of the |
| 1220 |
information in the statfs structure. |
| 1221 |
|
| 1222 |
As with the return stack, it would be possible (and a small performance win) |
| 1223 |
to pre-extend the return array before pushing data into it, since we know |
| 1224 |
how many elements we will return: |
| 1225 |
|
| 1226 |
av_extend(results, numpaths); |
| 1227 |
|
| 1228 |
=item * |
| 1229 |
|
| 1230 |
We are performing only one hash operation in this function, which is storing |
| 1231 |
a new scalar under a key using C<hv_store>. A hash is represented by an HV* |
| 1232 |
pointer. Like arrays, the functions for manipulating hashes from an XSUB |
| 1233 |
mirror the functionality available from Perl. See L<perlguts> and L<perlapi> |
| 1234 |
for details. |
| 1235 |
|
| 1236 |
=item * |
| 1237 |
|
| 1238 |
To create a reference, we use the C<newRV_inc> function. Note that you can |
| 1239 |
cast an AV* or an HV* to type SV* in this case (and many others). This |
| 1240 |
allows you to take references to arrays, hashes and scalars with the same |
| 1241 |
function. Conversely, the C<SvRV> function always returns an SV*, which may |
| 1242 |
need to be cast to the appropriate type if it is something other than a |
| 1243 |
scalar (check with C<SvTYPE>). |
| 1244 |
|
| 1245 |
=item * |
| 1246 |
|
| 1247 |
At this point, xsubpp is doing very little work - the differences between |
| 1248 |
Mytest.xs and Mytest.c are minimal. |
| 1249 |
|
| 1250 |
=back |
| 1251 |
|
| 1252 |
=head2 EXAMPLE 7 (Coming Soon) |
| 1253 |
|
| 1254 |
XPUSH args AND set RETVAL AND assign return value to array |
| 1255 |
|
| 1256 |
=head2 EXAMPLE 8 (Coming Soon) |
| 1257 |
|
| 1258 |
Setting $! |
| 1259 |
|
| 1260 |
=head2 EXAMPLE 9 Passing open files to XSes |
| 1261 |
|
| 1262 |
You would think passing files to an XS is difficult, with all the |
| 1263 |
typeglobs and stuff. Well, it isn't. |
| 1264 |
|
| 1265 |
Suppose that for some strange reason we need a wrapper around the |
| 1266 |
standard C library function C<fputs()>. This is all we need: |
| 1267 |
|
| 1268 |
#define PERLIO_NOT_STDIO 0 /* For co-existence with stdio only */ |
| 1269 |
#define PERL_NO_GET_CONTEXT /* This is more efficient */ |
| 1270 |
#include "EXTERN.h" |
| 1271 |
#include "perl.h" |
| 1272 |
#include "XSUB.h" |
| 1273 |
|
| 1274 |
#include <stdio.h> |
| 1275 |
|
| 1276 |
int |
| 1277 |
fputs(s, stream) |
| 1278 |
char * s |
| 1279 |
FILE * stream |
| 1280 |
|
| 1281 |
The real work is done in the standard typemap. |
| 1282 |
|
| 1283 |
For more details, see |
| 1284 |
L<perlapio/"Co-existence with stdio">. |
| 1285 |
|
| 1286 |
B<But> you lose all the fine stuff done by the perlio layers. This |
| 1287 |
calls the stdio function C<fputs()>, which knows nothing about them. |
| 1288 |
|
| 1289 |
The standard typemap offers three variants of PerlIO *: |
| 1290 |
C<InputStream> (T_IN), C<InOutStream> (T_INOUT) and C<OutputStream> |
| 1291 |
(T_OUT). A bare C<PerlIO *> is considered a T_INOUT. If it matters |
| 1292 |
in your code (see below for why it might) #define or typedef |
| 1293 |
one of the specific names and use that as the argument or result |
| 1294 |
type in your XS file. |
| 1295 |
|
| 1296 |
The standard typemap does not contain PerlIO * before perl 5.7, |
| 1297 |
but it has the three stream variants. Using a PerlIO * directly |
| 1298 |
is not backwards compatible unless you provide your own typemap. |
| 1299 |
|
| 1300 |
For streams coming I<from> perl the main difference is that |
| 1301 |
C<OutputStream> will get the output PerlIO * - which may make |
| 1302 |
a difference on a socket. Like in our example... |
| 1303 |
|
| 1304 |
For streams being handed I<to> perl a new file handle is created |
| 1305 |
(i.e. a reference to a new glob) and associated with the PerlIO * |
| 1306 |
provided. If the read/write state of the PerlIO * is not correct then you |
| 1307 |
may get errors or warnings from when the file handle is used. |
| 1308 |
So if you opened the PerlIO * as "w" it should really be an |
| 1309 |
C<OutputStream> if open as "r" it should be an C<InputStream>. |
| 1310 |
|
| 1311 |
Now, suppose you want to use perlio layers in your XS. We'll use the |
| 1312 |
perlio C<PerlIO_puts()> function as an example. |
| 1313 |
|
| 1314 |
In the C part of the XS file (above the first MODULE line) you |
| 1315 |
have |
| 1316 |
|
| 1317 |
#define OutputStream PerlIO * |
| 1318 |
or |
| 1319 |
typedef PerlIO * OutputStream; |
| 1320 |
|
| 1321 |
|
| 1322 |
And this is the XS code: |
| 1323 |
|
| 1324 |
int |
| 1325 |
perlioputs(s, stream) |
| 1326 |
char * s |
| 1327 |
OutputStream stream |
| 1328 |
CODE: |
| 1329 |
RETVAL = PerlIO_puts(stream, s); |
| 1330 |
OUTPUT: |
| 1331 |
RETVAL |
| 1332 |
|
| 1333 |
We have to use a C<CODE> section because C<PerlIO_puts()> has the arguments |
| 1334 |
reversed compared to C<fputs()>, and we want to keep the arguments the same. |
| 1335 |
|
| 1336 |
Wanting to explore this thoroughly, we want to use the stdio C<fputs()> |
| 1337 |
on a PerlIO *. This means we have to ask the perlio system for a stdio |
| 1338 |
C<FILE *>: |
| 1339 |
|
| 1340 |
int |
| 1341 |
perliofputs(s, stream) |
| 1342 |
char * s |
| 1343 |
OutputStream stream |
| 1344 |
PREINIT: |
| 1345 |
FILE *fp = PerlIO_findFILE(stream); |
| 1346 |
CODE: |
| 1347 |
if (fp != (FILE*) 0) { |
| 1348 |
RETVAL = fputs(s, fp); |
| 1349 |
} else { |
| 1350 |
RETVAL = -1; |
| 1351 |
} |
| 1352 |
OUTPUT: |
| 1353 |
RETVAL |
| 1354 |
|
| 1355 |
Note: C<PerlIO_findFILE()> will search the layers for a stdio |
| 1356 |
layer. If it can't find one, it will call C<PerlIO_exportFILE()> to |
| 1357 |
generate a new stdio C<FILE>. Please only call C<PerlIO_exportFILE()> if |
| 1358 |
you want a I<new> C<FILE>. It will generate one on each call and push a |
| 1359 |
new stdio layer. So don't call it repeatedly on the same |
| 1360 |
file. C<PerlIO_findFILE()> will retrieve the stdio layer once it has been |
| 1361 |
generated by C<PerlIO_exportFILE()>. |
| 1362 |
|
| 1363 |
This applies to the perlio system only. For versions before 5.7, |
| 1364 |
C<PerlIO_exportFILE()> is equivalent to C<PerlIO_findFILE()>. |
| 1365 |
|
| 1366 |
=head2 Troubleshooting these Examples |
| 1367 |
|
| 1368 |
As mentioned at the top of this document, if you are having problems with |
| 1369 |
these example extensions, you might see if any of these help you. |
| 1370 |
|
| 1371 |
=over 4 |
| 1372 |
|
| 1373 |
=item * |
| 1374 |
|
| 1375 |
In versions of 5.002 prior to the gamma version, the test script in Example |
| 1376 |
1 will not function properly. You need to change the "use lib" line to |
| 1377 |
read: |
| 1378 |
|
| 1379 |
use lib './blib'; |
| 1380 |
|
| 1381 |
=item * |
| 1382 |
|
| 1383 |
In versions of 5.002 prior to version 5.002b1h, the test.pl file was not |
| 1384 |
automatically created by h2xs. This means that you cannot say "make test" |
| 1385 |
to run the test script. You will need to add the following line before the |
| 1386 |
"use extension" statement: |
| 1387 |
|
| 1388 |
use lib './blib'; |
| 1389 |
|
| 1390 |
=item * |
| 1391 |
|
| 1392 |
In versions 5.000 and 5.001, instead of using the above line, you will need |
| 1393 |
to use the following line: |
| 1394 |
|
| 1395 |
BEGIN { unshift(@INC, "./blib") } |
| 1396 |
|
| 1397 |
=item * |
| 1398 |
|
| 1399 |
This document assumes that the executable named "perl" is Perl version 5. |
| 1400 |
Some systems may have installed Perl version 5 as "perl5". |
| 1401 |
|
| 1402 |
=back |
| 1403 |
|
| 1404 |
=head1 See also |
| 1405 |
|
| 1406 |
For more information, consult L<perlguts>, L<perlapi>, L<perlclib>, |
| 1407 |
L<perlxs>, L<perlmod>, |
| 1408 |
L<perlapio>, and L<perlpod> |
| 1409 |
|
| 1410 |
=head1 Author |
| 1411 |
|
| 1412 |
Jeff Okamoto <F<[email protected]>> |
| 1413 |
|
| 1414 |
Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig, |
| 1415 |
and Tim Bunce. |
| 1416 |
|
| 1417 |
PerlIO material contributed by Lupe Christoph, with some clarification |
| 1418 |
by Nick Ing-Simmons. |
| 1419 |
|
| 1420 |
Changes for h2xs as of Perl 5.8.x by Renee Baecker |
| 1421 |
|
| 1422 |
This document is now maintained as part of Perl itself. |
| 1423 |
|
| 1424 |
=head2 Last Changed |
| 1425 |
|
| 1426 |
2020-10-05 |