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