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