Commit | Line | Data |
4633a7c4 |
1 | =head1 NAME |
2 | |
360e660c |
3 | perlXStut - Tutorial for writing XSUBs |
4633a7c4 |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | This tutorial will educate the reader on the steps involved in creating |
c07a80fd |
8 | a Perl extension. The reader is assumed to have access to L<perlguts> and |
4633a7c4 |
9 | L<perlxs>. |
10 | |
11 | This tutorial starts with very simple examples and becomes more complex, |
c07a80fd |
12 | with each new example adding new features. Certain concepts may not be |
360e660c |
13 | completely explained until later in the tutorial in order to slowly ease |
14 | the reader into building extensions. |
4633a7c4 |
15 | |
360e660c |
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. |
4633a7c4 |
19 | |
360e660c |
20 | =head1 SPECIAL NOTES |
c07a80fd |
21 | |
360e660c |
22 | =head2 make |
c07a80fd |
23 | |
360e660c |
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 |
5a3e7812 |
27 | configured to use. Running B<perl -V:make> should tell you what it is. |
c07a80fd |
28 | |
360e660c |
29 | =head2 Version caveat |
c07a80fd |
30 | |
beb31b0b |
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 |
c07a80fd |
58 | |
360e660c |
59 | =head2 Dynamic Loading versus Static Loading |
c07a80fd |
60 | |
61 | It is commonly thought that if a system does not have the capability to |
360e660c |
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 |
c07a80fd |
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, |
360e660c |
74 | where the command "C<make>" with no arguments is executed, run the command |
75 | "C<make perl>" instead. |
c07a80fd |
76 | |
77 | If you have generated such a statically-linked executable by choice, then |
360e660c |
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! |
c07a80fd |
85 | |
86 | =head2 EXAMPLE 1 |
4633a7c4 |
87 | |
88 | Our first extension will be very simple. When we call the routine in the |
c07a80fd |
89 | extension, it will print out a well-known message and return. |
4633a7c4 |
90 | |
360e660c |
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. |
4633a7c4 |
95 | |
360e660c |
96 | The MANIFEST file contains the names of all the files just created in the |
97 | Mytest directory. |
4633a7c4 |
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( |
360e660c |
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' |
4633a7c4 |
110 | ); |
111 | |
791fa977 |
112 | The file Mytest.pm should start with something like this: |
c07a80fd |
113 | |
791fa977 |
114 | package Mytest; |
4633a7c4 |
115 | |
360e660c |
116 | use strict; |
9f1b1f2d |
117 | use warnings; |
360e660c |
118 | |
4633a7c4 |
119 | require Exporter; |
120 | require DynaLoader; |
c07a80fd |
121 | |
77ca0c92 |
122 | our @ISA = qw(Exporter DynaLoader); |
4633a7c4 |
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. |
77ca0c92 |
126 | our @EXPORT = qw( |
c07a80fd |
127 | |
4633a7c4 |
128 | ); |
77ca0c92 |
129 | our $VERSION = '0.01'; |
c07a80fd |
130 | |
791fa977 |
131 | bootstrap Mytest $VERSION; |
c07a80fd |
132 | |
4633a7c4 |
133 | # Preloaded methods go here. |
c07a80fd |
134 | |
4633a7c4 |
135 | # Autoload methods go after __END__, and are processed by the autosplit program. |
c07a80fd |
136 | |
4633a7c4 |
137 | 1; |
138 | __END__ |
c07a80fd |
139 | # Below is the stub of documentation for your module. You better edit it! |
4633a7c4 |
140 | |
360e660c |
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: |
4633a7c4 |
145 | |
146 | #include "EXTERN.h" |
147 | #include "perl.h" |
148 | #include "XSUB.h" |
791fa977 |
149 | |
150 | MODULE = Mytest PACKAGE = Mytest |
4633a7c4 |
151 | |
152 | Let's edit the .xs file by adding this to the end of the file: |
153 | |
154 | void |
155 | hello() |
360e660c |
156 | CODE: |
4633a7c4 |
157 | printf("Hello, world!\n"); |
158 | |
360e660c |
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, |
d9d2a7fb |
164 | which make needs. Its output looks something like: |
4633a7c4 |
165 | |
166 | % perl Makefile.PL |
167 | Checking if your kit is complete... |
168 | Looks good |
791fa977 |
169 | Writing Makefile for Mytest |
4633a7c4 |
170 | % |
171 | |
360e660c |
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): |
4633a7c4 |
175 | |
176 | % make |
791fa977 |
177 | umask 0 && cp Mytest.pm ./blib/Mytest.pm |
178 | perl xsubpp -typemap typemap Mytest.xs >Mytest.tc && mv Mytest.tc Mytest.c |
360e660c |
179 | Please specify prototyping behavior for Mytest.xs (see perlxs manual) |
791fa977 |
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 |
360e660c |
187 | Manifying ./blib/man3/Mytest.3 |
188 | % |
189 | |
190 | You can safely ignore the line about "prototyping behavior". |
191 | |
192 | If you are on a Win32 system, and the build process fails with linker |
193 | errors for functions in the C library, check if your Perl is configured |
5a3e7812 |
194 | to use PerlCRT (running B<perl -V:libc> should show you if this is the |
360e660c |
195 | case). If Perl is configured to use PerlCRT, you have to make sure |
196 | PerlCRT.lib is copied to the same location that msvcrt.lib lives in, |
197 | so that the compiler can find it on its own. msvcrt.lib is usually |
198 | found in the Visual C compiler's lib directory (e.g. C:/DevStudio/VC/lib). |
c07a80fd |
199 | |
360e660c |
200 | Perl has its own special way of easily writing test scripts, but for this |
201 | example only, we'll create our own test script. Create a file called hello |
c07a80fd |
202 | that looks like this: |
203 | |
c07a80fd |
204 | #! /opt/perl5/bin/perl |
c47ff5f1 |
205 | |
d9d2a7fb |
206 | use ExtUtils::testlib; |
c47ff5f1 |
207 | |
791fa977 |
208 | use Mytest; |
c47ff5f1 |
209 | |
791fa977 |
210 | Mytest::hello(); |
4633a7c4 |
211 | |
360e660c |
212 | Now we make the script executable (C<chmod -x hello>), run the script |
213 | and we should see the following output: |
4633a7c4 |
214 | |
360e660c |
215 | % ./hello |
4633a7c4 |
216 | Hello, world! |
217 | % |
218 | |
c07a80fd |
219 | =head2 EXAMPLE 2 |
4633a7c4 |
220 | |
360e660c |
221 | Now let's add to our extension a subroutine that will take a single numeric |
222 | argument as input and return 0 if the number is even or 1 if the number |
223 | is odd. |
4633a7c4 |
224 | |
791fa977 |
225 | Add the following to the end of Mytest.xs: |
4633a7c4 |
226 | |
227 | int |
228 | is_even(input) |
229 | int input |
360e660c |
230 | CODE: |
c07a80fd |
231 | RETVAL = (input % 2 == 0); |
360e660c |
232 | OUTPUT: |
4633a7c4 |
233 | RETVAL |
234 | |
360e660c |
235 | There does not need to be white space at the start of the "C<int input>" |
236 | line, but it is useful for improving readability. Placing a semi-colon at |
237 | the end of that line is also optional. Any amount and kind of white space |
238 | may be placed between the "C<int>" and "C<input>". |
4633a7c4 |
239 | |
360e660c |
240 | Now re-run make to rebuild our new shared library. |
4633a7c4 |
241 | |
c07a80fd |
242 | Now perform the same steps as before, generating a Makefile from the |
243 | Makefile.PL file, and running make. |
4633a7c4 |
244 | |
360e660c |
245 | In order to test that our extension works, we now need to look at the |
c07a80fd |
246 | file test.pl. This file is set up to imitate the same kind of testing |
247 | structure that Perl itself has. Within the test script, you perform a |
248 | number of tests to confirm the behavior of the extension, printing "ok" |
d9d2a7fb |
249 | when the test is correct, "not ok" when it is not. Change the print |
250 | statement in the BEGIN block to print "1..4", and add the following code |
251 | to the end of the file: |
c07a80fd |
252 | |
791fa977 |
253 | print &Mytest::is_even(0) == 1 ? "ok 2" : "not ok 2", "\n"; |
254 | print &Mytest::is_even(1) == 0 ? "ok 3" : "not ok 3", "\n"; |
255 | print &Mytest::is_even(2) == 1 ? "ok 4" : "not ok 4", "\n"; |
c07a80fd |
256 | |
360e660c |
257 | We will be calling the test script through the command "C<make test>". You |
c07a80fd |
258 | should see output that looks something like this: |
259 | |
260 | % make test |
360e660c |
261 | PERL_DL_NONLAZY=1 /opt/perl5.004/bin/perl (lots of -I arguments) test.pl |
c07a80fd |
262 | 1..4 |
263 | ok 1 |
264 | ok 2 |
265 | ok 3 |
266 | ok 4 |
4633a7c4 |
267 | % |
268 | |
360e660c |
269 | =head2 What has gone on? |
4633a7c4 |
270 | |
271 | The program h2xs is the starting point for creating extensions. In later |
c07a80fd |
272 | examples we'll see how we can use h2xs to read header files and generate |
4633a7c4 |
273 | templates to connect to C routines. |
274 | |
275 | h2xs creates a number of files in the extension directory. The file |
276 | Makefile.PL is a perl script which will generate a true Makefile to build |
277 | the extension. We'll take a closer look at it later. |
278 | |
360e660c |
279 | The .pm and .xs files contain the meat of the extension. The .xs file holds |
280 | the C routines that make up the extension. The .pm file contains routines |
281 | that tell Perl how to load your extension. |
282 | |
283 | Generating the Makefile and running C<make> created a directory called blib |
284 | (which stands for "build library") in the current working directory. This |
285 | directory will contain the shared library that we will build. Once we have |
286 | tested it, we can install it into its final location. |
287 | |
288 | Invoking the test script via "C<make test>" did something very important. |
289 | It invoked perl with all those C<-I> arguments so that it could find the |
290 | various files that are part of the extension. It is I<very> important that |
291 | while you are still testing extensions that you use "C<make test>". If you |
292 | try to run the test script all by itself, you will get a fatal error. |
293 | Another reason it is important to use "C<make test>" to run your test |
294 | script is that if you are testing an upgrade to an already-existing version, |
295 | using "C<make test>" insures that you will test your new extension, not the |
296 | already-existing version. |
4633a7c4 |
297 | |
c07a80fd |
298 | When Perl sees a C<use extension;>, it searches for a file with the same name |
360e660c |
299 | as the C<use>'d extension that has a .pm suffix. If that file cannot be found, |
c07a80fd |
300 | Perl dies with a fatal error. The default search path is contained in the |
360e660c |
301 | C<@INC> array. |
4633a7c4 |
302 | |
791fa977 |
303 | In our case, Mytest.pm tells perl that it will need the Exporter and Dynamic |
360e660c |
304 | Loader extensions. It then sets the C<@ISA> and C<@EXPORT> arrays and the |
305 | C<$VERSION> scalar; finally it tells perl to bootstrap the module. Perl |
306 | will call its dynamic loader routine (if there is one) and load the shared |
307 | library. |
4633a7c4 |
308 | |
360e660c |
309 | The two arrays C<@ISA> and C<@EXPORT> are very important. The C<@ISA> |
c07a80fd |
310 | array contains a list of other packages in which to search for methods (or |
360e660c |
311 | subroutines) that do not exist in the current package. This is usually |
312 | only important for object-oriented extensions (which we will talk about |
313 | much later), and so usually doesn't need to be modified. |
4633a7c4 |
314 | |
360e660c |
315 | The C<@EXPORT> array tells Perl which of the extension's variables and |
316 | subroutines should be placed into the calling package's namespace. Because |
317 | you don't know if the user has already used your variable and subroutine |
318 | names, it's vitally important to carefully select what to export. Do I<not> |
319 | export method or variable names I<by default> without a good reason. |
4633a7c4 |
320 | |
c07a80fd |
321 | As a general rule, if the module is trying to be object-oriented then don't |
360e660c |
322 | export anything. If it's just a collection of functions and variables, then |
323 | you can export them via another array, called C<@EXPORT_OK>. This array |
324 | does not automatically place its subroutine and variable names into the |
325 | namespace unless the user specifically requests that this be done. |
4633a7c4 |
326 | |
c07a80fd |
327 | See L<perlmod> for more information. |
4633a7c4 |
328 | |
360e660c |
329 | The C<$VERSION> variable is used to ensure that the .pm file and the shared |
791fa977 |
330 | library are "in sync" with each other. Any time you make changes to |
331 | the .pm or .xs files, you should increment the value of this variable. |
332 | |
360e660c |
333 | =head2 Writing good test scripts |
791fa977 |
334 | |
335 | The importance of writing good test scripts cannot be overemphasized. You |
336 | should closely follow the "ok/not ok" style that Perl itself uses, so that |
337 | it is very easy and unambiguous to determine the outcome of each test case. |
338 | When you find and fix a bug, make sure you add a test case for it. |
339 | |
360e660c |
340 | By running "C<make test>", you ensure that your test.pl script runs and uses |
791fa977 |
341 | the correct version of your extension. If you have many test cases, you |
360e660c |
342 | might want to copy Perl's test style. Create a directory named "t" in the |
343 | extension's directory and append the suffix ".t" to the names of your test |
344 | files. When you run "C<make test>", all of these test files will be executed. |
4633a7c4 |
345 | |
c07a80fd |
346 | =head2 EXAMPLE 3 |
4633a7c4 |
347 | |
348 | Our third extension will take one argument as its input, round off that |
c07a80fd |
349 | value, and set the I<argument> to the rounded value. |
4633a7c4 |
350 | |
791fa977 |
351 | Add the following to the end of Mytest.xs: |
4633a7c4 |
352 | |
353 | void |
354 | round(arg) |
355 | double arg |
360e660c |
356 | CODE: |
4633a7c4 |
357 | if (arg > 0.0) { |
358 | arg = floor(arg + 0.5); |
359 | } else if (arg < 0.0) { |
360 | arg = ceil(arg - 0.5); |
361 | } else { |
362 | arg = 0.0; |
363 | } |
360e660c |
364 | OUTPUT: |
4633a7c4 |
365 | arg |
366 | |
c07a80fd |
367 | Edit the Makefile.PL file so that the corresponding line looks like this: |
4633a7c4 |
368 | |
369 | 'LIBS' => ['-lm'], # e.g., '-lm' |
370 | |
360e660c |
371 | Generate the Makefile and run make. Change the BEGIN block to print |
c07a80fd |
372 | "1..9" and add the following to test.pl: |
4633a7c4 |
373 | |
791fa977 |
374 | $i = -1.5; &Mytest::round($i); print $i == -2.0 ? "ok 5" : "not ok 5", "\n"; |
375 | $i = -1.1; &Mytest::round($i); print $i == -1.0 ? "ok 6" : "not ok 6", "\n"; |
376 | $i = 0.0; &Mytest::round($i); print $i == 0.0 ? "ok 7" : "not ok 7", "\n"; |
377 | $i = 0.5; &Mytest::round($i); print $i == 1.0 ? "ok 8" : "not ok 8", "\n"; |
378 | $i = 1.2; &Mytest::round($i); print $i == 1.0 ? "ok 9" : "not ok 9", "\n"; |
c07a80fd |
379 | |
360e660c |
380 | Running "C<make test>" should now print out that all nine tests are okay. |
4633a7c4 |
381 | |
360e660c |
382 | Notice that in these new test cases, the argument passed to round was a |
383 | scalar variable. You might be wondering if you can round a constant or |
384 | literal. To see what happens, temporarily add the following line to test.pl: |
4633a7c4 |
385 | |
791fa977 |
386 | &Mytest::round(3); |
4633a7c4 |
387 | |
360e660c |
388 | Run "C<make test>" and notice that Perl dies with a fatal error. Perl won't |
389 | let you change the value of constants! |
4633a7c4 |
390 | |
360e660c |
391 | =head2 What's new here? |
4633a7c4 |
392 | |
360e660c |
393 | =over 4 |
4633a7c4 |
394 | |
360e660c |
395 | =item * |
4633a7c4 |
396 | |
360e660c |
397 | We've made some changes to Makefile.PL. In this case, we've specified an |
398 | extra library to be linked into the extension's shared library, the math |
399 | library libm in this case. We'll talk later about how to write XSUBs that |
400 | can call every routine in a library. |
4633a7c4 |
401 | |
360e660c |
402 | =item * |
403 | |
404 | The value of the function is not being passed back as the function's return |
405 | value, but by changing the value of the variable that was passed into the |
406 | function. You might have guessed that when you saw that the return value |
407 | of round is of type "void". |
408 | |
409 | =back |
410 | |
411 | =head2 Input and Output Parameters |
4633a7c4 |
412 | |
360e660c |
413 | You specify the parameters that will be passed into the XSUB on the line(s) |
414 | after you declare the function's return value and name. Each input parameter |
415 | line starts with optional white space, and may have an optional terminating |
416 | semicolon. |
4633a7c4 |
417 | |
360e660c |
418 | The list of output parameters occurs at the very end of the function, just |
419 | before after the OUTPUT: directive. The use of RETVAL tells Perl that you |
420 | wish to send this value back as the return value of the XSUB function. In |
421 | Example 3, we wanted the "return value" placed in the original variable |
422 | which we passed in, so we listed it (and not RETVAL) in the OUTPUT: section. |
4633a7c4 |
423 | |
360e660c |
424 | =head2 The XSUBPP Program |
425 | |
beb31b0b |
426 | The B<xsubpp> program takes the XS code in the .xs file and translates it into |
4633a7c4 |
427 | C code, placing it in a file whose suffix is .c. The C code created makes |
428 | heavy use of the C functions within Perl. |
429 | |
360e660c |
430 | =head2 The TYPEMAP file |
4633a7c4 |
431 | |
beb31b0b |
432 | The B<xsubpp> program uses rules to convert from Perl's data types (scalar, |
360e660c |
433 | array, etc.) to C's data types (int, char, etc.). These rules are stored |
4633a7c4 |
434 | in the typemap file ($PERLLIB/ExtUtils/typemap). This file is split into |
435 | three parts. |
436 | |
360e660c |
437 | The first section maps various C data types to a name, which corresponds |
438 | somewhat with the various Perl types. The second section contains C code |
beb31b0b |
439 | which B<xsubpp> uses to handle input parameters. The third section contains |
440 | C code which B<xsubpp> uses to handle output parameters. |
4633a7c4 |
441 | |
360e660c |
442 | Let's take a look at a portion of the .c file created for our extension. |
443 | The file name is Mytest.c: |
4633a7c4 |
444 | |
791fa977 |
445 | XS(XS_Mytest_round) |
4633a7c4 |
446 | { |
447 | dXSARGS; |
c07a80fd |
448 | if (items != 1) |
791fa977 |
449 | croak("Usage: Mytest::round(arg)"); |
4633a7c4 |
450 | { |
c07a80fd |
451 | double arg = (double)SvNV(ST(0)); /* XXXXX */ |
4633a7c4 |
452 | if (arg > 0.0) { |
453 | arg = floor(arg + 0.5); |
454 | } else if (arg < 0.0) { |
455 | arg = ceil(arg - 0.5); |
c07a80fd |
456 | } else { |
457 | arg = 0.0; |
4633a7c4 |
458 | } |
360e660c |
459 | sv_setnv(ST(0), (double)arg); /* XXXXX */ |
4633a7c4 |
460 | } |
461 | XSRETURN(1); |
462 | } |
4633a7c4 |
463 | |
360e660c |
464 | Notice the two lines commented with "XXXXX". If you check the first section |
465 | of the typemap file, you'll see that doubles are of type T_DOUBLE. In the |
4633a7c4 |
466 | INPUT section, an argument that is T_DOUBLE is assigned to the variable |
467 | arg by calling the routine SvNV on something, then casting it to double, |
468 | then assigned to the variable arg. Similarly, in the OUTPUT section, |
ef50df4b |
469 | once arg has its final value, it is passed to the sv_setnv function to |
470 | be passed back to the calling subroutine. These two functions are explained |
471 | in L<perlguts>; we'll talk more later about what that "ST(0)" means in the |
472 | section on the argument stack. |
4633a7c4 |
473 | |
360e660c |
474 | =head2 Warning about Output Arguments |
4633a7c4 |
475 | |
c07a80fd |
476 | In general, it's not a good idea to write extensions that modify their input |
360e660c |
477 | parameters, as in Example 3. Instead, you should probably return multiple |
478 | values in an array and let the caller handle them (we'll do this in a later |
479 | example). However, in order to better accomodate calling pre-existing C |
480 | routines, which often do modify their input parameters, this behavior is |
481 | tolerated. |
791fa977 |
482 | |
483 | =head2 EXAMPLE 4 |
484 | |
68dc0745 |
485 | In this example, we'll now begin to write XSUBs that will interact with |
360e660c |
486 | pre-defined C libraries. To begin with, we will build a small library of |
791fa977 |
487 | our own, then let h2xs write our .pm and .xs files for us. |
488 | |
489 | Create a new directory called Mytest2 at the same level as the directory |
490 | Mytest. In the Mytest2 directory, create another directory called mylib, |
491 | and cd into that directory. |
492 | |
493 | Here we'll create some files that will generate a test library. These will |
494 | include a C source file and a header file. We'll also create a Makefile.PL |
495 | in this directory. Then we'll make sure that running make at the Mytest2 |
496 | level will automatically run this Makefile.PL file and the resulting Makefile. |
497 | |
9693b09d |
498 | In the mylib directory, create a file mylib.h that looks like this: |
791fa977 |
499 | |
500 | #define TESTVAL 4 |
501 | |
502 | extern double foo(int, long, const char*); |
503 | |
504 | Also create a file mylib.c that looks like this: |
505 | |
506 | #include <stdlib.h> |
507 | #include "./mylib.h" |
c47ff5f1 |
508 | |
791fa977 |
509 | double |
360e660c |
510 | foo(int a, long b, const char *c) |
791fa977 |
511 | { |
512 | return (a + b + atof(c) + TESTVAL); |
513 | } |
514 | |
515 | And finally create a file Makefile.PL that looks like this: |
516 | |
517 | use ExtUtils::MakeMaker; |
518 | $Verbose = 1; |
519 | WriteMakefile( |
360e660c |
520 | NAME => 'Mytest2::mylib', |
521 | SKIP => [qw(all static static_lib dynamic dynamic_lib)], |
522 | clean => {'FILES' => 'libmylib$(LIBEEXT)'}, |
791fa977 |
523 | ); |
524 | |
525 | |
8227f81c |
526 | sub MY::top_targets { |
791fa977 |
527 | ' |
528 | all :: static |
529 | |
360e660c |
530 | pure_all :: static |
531 | |
791fa977 |
532 | static :: libmylib$(LIB_EXT) |
533 | |
534 | libmylib$(LIB_EXT): $(O_FILES) |
535 | $(AR) cr libmylib$(LIB_EXT) $(O_FILES) |
536 | $(RANLIB) libmylib$(LIB_EXT) |
537 | |
538 | '; |
539 | } |
540 | |
360e660c |
541 | Make sure you use a tab and not spaces on the lines beginning with "$(AR)" |
542 | and "$(RANLIB)". Make will not function properly if you use spaces. |
543 | It has also been reported that the "cr" argument to $(AR) is unnecessary |
544 | on Win32 systems. |
545 | |
791fa977 |
546 | We will now create the main top-level Mytest2 files. Change to the directory |
547 | above Mytest2 and run the following command: |
548 | |
d9d2a7fb |
549 | % h2xs -O -n Mytest2 ./Mytest2/mylib/mylib.h |
791fa977 |
550 | |
551 | This will print out a warning about overwriting Mytest2, but that's okay. |
552 | Our files are stored in Mytest2/mylib, and will be untouched. |
553 | |
554 | The normal Makefile.PL that h2xs generates doesn't know about the mylib |
555 | directory. We need to tell it that there is a subdirectory and that we |
360e660c |
556 | will be generating a library in it. Let's add the argument MYEXTLIB to |
557 | the WriteMakefile call so that it looks like this: |
4633a7c4 |
558 | |
360e660c |
559 | WriteMakefile( |
560 | 'NAME' => 'Mytest2', |
561 | 'VERSION_FROM' => 'Mytest2.pm', # finds $VERSION |
562 | 'LIBS' => [''], # e.g., '-lm' |
563 | 'DEFINE' => '', # e.g., '-DHAVE_SOMETHING' |
564 | 'INC' => '', # e.g., '-I/usr/include/other' |
565 | 'MYEXTLIB' => 'mylib/libmylib$(LIB_EXT)', |
566 | ); |
791fa977 |
567 | |
360e660c |
568 | and then at the end add a subroutine (which will override the pre-existing |
569 | subroutine). Remember to use a tab character to indent the line beginning |
570 | with "cd"! |
791fa977 |
571 | |
572 | sub MY::postamble { |
573 | ' |
574 | $(MYEXTLIB): mylib/Makefile |
360e660c |
575 | cd mylib && $(MAKE) $(PASSTHRU) |
791fa977 |
576 | '; |
577 | } |
578 | |
791fa977 |
579 | Let's also fix the MANIFEST file so that it accurately reflects the contents |
580 | of our extension. The single line that says "mylib" should be replaced by |
581 | the following three lines: |
582 | |
583 | mylib/Makefile.PL |
584 | mylib/mylib.c |
585 | mylib/mylib.h |
586 | |
587 | To keep our namespace nice and unpolluted, edit the .pm file and change |
77ca0c92 |
588 | the variable C<@EXPORT> to C<@EXPORT_OK>. Finally, in the |
d9d2a7fb |
589 | .xs file, edit the #include line to read: |
791fa977 |
590 | |
591 | #include "mylib/mylib.h" |
592 | |
593 | And also add the following function definition to the end of the .xs file: |
594 | |
595 | double |
596 | foo(a,b,c) |
597 | int a |
598 | long b |
599 | const char * c |
360e660c |
600 | OUTPUT: |
791fa977 |
601 | RETVAL |
602 | |
603 | Now we also need to create a typemap file because the default Perl doesn't |
360e660c |
604 | currently support the const char * type. Create a file called typemap in |
605 | the Mytest2 directory and place the following in it: |
791fa977 |
606 | |
607 | const char * T_PV |
608 | |
609 | Now run perl on the top-level Makefile.PL. Notice that it also created a |
360e660c |
610 | Makefile in the mylib directory. Run make and watch that it does cd into |
791fa977 |
611 | the mylib directory and run make in there as well. |
612 | |
613 | Now edit the test.pl script and change the BEGIN block to print "1..4", |
614 | and add the following lines to the end of the script: |
615 | |
616 | print &Mytest2::foo(1, 2, "Hello, world!") == 7 ? "ok 2\n" : "not ok 2\n"; |
617 | print &Mytest2::foo(1, 2, "0.0") == 7 ? "ok 3\n" : "not ok 3\n"; |
618 | print abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 ? "ok 4\n" : "not ok 4\n"; |
619 | |
360e660c |
620 | (When dealing with floating-point comparisons, it is best to not check for |
621 | equality, but rather that the difference between the expected and actual |
622 | result is below a certain amount (called epsilon) which is 0.01 in this case) |
791fa977 |
623 | |
360e660c |
624 | Run "C<make test>" and all should be well. |
791fa977 |
625 | |
360e660c |
626 | =head2 What has happened here? |
791fa977 |
627 | |
628 | Unlike previous examples, we've now run h2xs on a real include file. This |
629 | has caused some extra goodies to appear in both the .pm and .xs files. |
630 | |
84dc3c4d |
631 | =over 4 |
632 | |
791fa977 |
633 | =item * |
634 | |
360e660c |
635 | In the .xs file, there's now a #include directive with the absolute path to |
636 | the mylib.h header file. We changed this to a relative path so that we |
637 | could move the extension directory if we wanted to. |
791fa977 |
638 | |
639 | =item * |
640 | |
641 | There's now some new C code that's been added to the .xs file. The purpose |
642 | of the C<constant> routine is to make the values that are #define'd in the |
360e660c |
643 | header file accessible by the Perl script (by calling either C<TESTVAL> or |
644 | C<&Mytest2::TESTVAL>). There's also some XS code to allow calls to the |
791fa977 |
645 | C<constant> routine. |
646 | |
647 | =item * |
648 | |
360e660c |
649 | The .pm file originally exported the name C<TESTVAL> in the C<@EXPORT> array. |
650 | This could lead to name clashes. A good rule of thumb is that if the #define |
651 | is only going to be used by the C routines themselves, and not by the user, |
652 | they should be removed from the C<@EXPORT> array. Alternately, if you don't |
653 | mind using the "fully qualified name" of a variable, you could move most |
654 | or all of the items from the C<@EXPORT> array into the C<@EXPORT_OK> array. |
791fa977 |
655 | |
d9d2a7fb |
656 | =item * |
657 | |
360e660c |
658 | If our include file had contained #include directives, these would not have |
659 | been processed by h2xs. There is no good solution to this right now. |
d9d2a7fb |
660 | |
360e660c |
661 | =item * |
791fa977 |
662 | |
663 | We've also told Perl about the library that we built in the mylib |
360e660c |
664 | subdirectory. That required only the addition of the C<MYEXTLIB> variable |
791fa977 |
665 | to the WriteMakefile call and the replacement of the postamble subroutine |
666 | to cd into the subdirectory and run make. The Makefile.PL for the |
667 | library is a bit more complicated, but not excessively so. Again we |
668 | replaced the postamble subroutine to insert our own code. This code |
360e660c |
669 | simply specified that the library to be created here was a static archive |
670 | library (as opposed to a dynamically loadable library) and provided the |
791fa977 |
671 | commands to build it. |
4633a7c4 |
672 | |
360e660c |
673 | =back |
674 | |
beb31b0b |
675 | =head2 Anatomy of .xs file |
676 | |
677 | The .xs file of L<"EXAMPLE 4"> contained some new elements. To understand |
678 | the meaning of these elements, pay attention to the line which reads |
679 | |
680 | MODULE = Mytest2 PACKAGE = Mytest2 |
681 | |
682 | Anything before this line is plain C code which describes which headers |
683 | to include, and defines some convenience functions. No translations are |
684 | performed on this part, it goes into the generated output C file as is. |
685 | |
686 | Anything after this line is the description of XSUB functions. |
687 | These descriptions are translated by B<xsubpp> into C code which |
688 | implements these functions using Perl calling conventions, and which |
689 | makes these functions visible from Perl interpreter. |
690 | |
691 | Pay a special attention to the function C<constant>. This name appears |
692 | twice in the generated .xs file: once in the first part, as a static C |
693 | function, the another time in the second part, when an XSUB interface to |
694 | this static C function is defined. |
695 | |
696 | This is quite typical for .xs files: usually the .xs file provides |
697 | an interface to an existing C function. Then this C function is defined |
698 | somewhere (either in an external library, or in the first part of .xs file), |
699 | and a Perl interface to this function (i.e. "Perl glue") is described in the |
700 | second part of .xs file. The situation in L<"EXAMPLE 1">, L<"EXAMPLE 2">, |
701 | and L<"EXAMPLE 3">, when all the work is done inside the "Perl glue", is |
702 | somewhat of an exception rather than the rule. |
703 | |
704 | =head2 Getting the fat out of XSUBs |
705 | |
706 | In L<"EXAMPLE 4"> the second part of .xs file contained the following |
707 | description of an XSUB: |
708 | |
709 | double |
710 | foo(a,b,c) |
711 | int a |
712 | long b |
713 | const char * c |
714 | OUTPUT: |
715 | RETVAL |
716 | |
717 | Note that in contrast with L<"EXAMPLE 1">, L<"EXAMPLE 2"> and L<"EXAMPLE 3">, |
718 | this description does not contain the actual I<code> for what is done |
719 | is done during a call to Perl function foo(). To understand what is going |
720 | on here, one can add a CODE section to this XSUB: |
721 | |
722 | double |
723 | foo(a,b,c) |
724 | int a |
725 | long b |
726 | const char * c |
727 | CODE: |
728 | RETVAL = foo(a,b,c); |
729 | OUTPUT: |
730 | RETVAL |
731 | |
732 | However, these two XSUBs provide almost identical generated C code: B<xsubpp> |
733 | compiler is smart enough to figure out the C<CODE:> section from the first |
734 | two lines of the description of XSUB. What about C<OUTPUT:> section? In |
735 | fact, that is absolutely the same! The C<OUTPUT:> section can be removed |
736 | as well, I<as far as C<CODE:> section or C<PPCODE:> section> is not |
737 | specified: B<xsubpp> can see that it needs to generate a function call |
738 | section, and will autogenerate the OUTPUT section too. Thus one can |
739 | shortcut the XSUB to become: |
740 | |
741 | double |
742 | foo(a,b,c) |
743 | int a |
744 | long b |
745 | const char * c |
746 | |
747 | Can we do the same with an XSUB |
748 | |
749 | int |
750 | is_even(input) |
751 | int input |
752 | CODE: |
753 | RETVAL = (input % 2 == 0); |
754 | OUTPUT: |
755 | RETVAL |
756 | |
757 | of L<"EXAMPLE 2">? To do this, one needs to define a C function C<int |
758 | is_even(int input)>. As we saw in L<Anatomy of .xs file>, a proper place |
759 | for this definition is in the first part of .xs file. In fact a C function |
760 | |
761 | int |
762 | is_even(int arg) |
763 | { |
764 | return (arg % 2 == 0); |
765 | } |
766 | |
767 | is probably overkill for this. Something as simple as a C<#define> will |
768 | do too: |
769 | |
770 | #define is_even(arg) ((arg) % 2 == 0) |
771 | |
772 | After having this in the first part of .xs file, the "Perl glue" part becomes |
773 | as simple as |
774 | |
775 | int |
776 | is_even(input) |
777 | int input |
778 | |
779 | This technique of separation of the glue part from the workhorse part has |
780 | obvious tradeoffs: if you want to change a Perl interface, you need to |
781 | change two places in your code. However, it removes a lot of clutter, |
782 | and makes the workhorse part independent from idiosyncrasies of Perl calling |
783 | convention. (In fact, there is nothing Perl-specific in the above description, |
784 | a different version of B<xsubpp> might have translated this to TCL glue or |
785 | Python glue as well.) |
786 | |
787 | =head2 More about XSUB arguments |
4633a7c4 |
788 | |
791fa977 |
789 | With the completion of Example 4, we now have an easy way to simulate some |
c07a80fd |
790 | real-life libraries whose interfaces may not be the cleanest in the world. |
791 | We shall now continue with a discussion of the arguments passed to the |
beb31b0b |
792 | B<xsubpp> compiler. |
4633a7c4 |
793 | |
360e660c |
794 | When you specify arguments to routines in the .xs file, you are really |
795 | passing three pieces of information for each argument listed. The first |
796 | piece is the order of that argument relative to the others (first, second, |
797 | etc). The second is the type of argument, and consists of the type |
798 | declaration of the argument (e.g., int, char*, etc). The third piece is |
beb31b0b |
799 | the calling convention for the argument in the call to the library function. |
800 | |
801 | While Perl passes arguments to functions by reference, |
802 | C passes arguments by value; to implement a C function which modifies data |
803 | of one of the "arguments", the actual argument of this C function would be |
804 | a pointer to the data. Thus two C functions with declarations |
805 | |
806 | int string_length(char *s); |
807 | int upper_case_char(char *cp); |
808 | |
809 | may have completely different semantics: the first one may inspect an array |
810 | of chars pointed by s, and the second one may immediately dereference C<cp> |
811 | and manipulate C<*cp> only (using the return value as, say, a success |
812 | indicator). From Perl one would use these functions in |
813 | a completely different manner. |
814 | |
815 | One conveys this info to B<xsubpp> by replacing C<*> before the |
816 | argument by C<&>. C<&> means that the argument should be passed to a library |
817 | function by its address. The above two function may be XSUB-ified as |
818 | |
819 | int |
820 | string_length(s) |
821 | char * s |
822 | |
823 | int |
824 | upper_case_char(cp) |
825 | char &cp |
4633a7c4 |
826 | |
beb31b0b |
827 | For example, consider: |
4633a7c4 |
828 | |
4633a7c4 |
829 | int |
c07a80fd |
830 | foo(a,b) |
831 | char &a |
832 | char * b |
4633a7c4 |
833 | |
beb31b0b |
834 | The first Perl argument to this function would be treated as a char and assigned |
c07a80fd |
835 | to the variable a, and its address would be passed into the function foo. |
beb31b0b |
836 | The second Perl argument would be treated as a string pointer and assigned to the |
c07a80fd |
837 | variable b. The I<value> of b would be passed into the function foo. The |
beb31b0b |
838 | actual call to the function foo that B<xsubpp> generates would look like this: |
4633a7c4 |
839 | |
c07a80fd |
840 | foo(&a, b); |
4633a7c4 |
841 | |
beb31b0b |
842 | B<xsubpp> will parse the following function argument lists identically: |
791fa977 |
843 | |
844 | char &a |
845 | char&a |
846 | char & a |
847 | |
848 | However, to help ease understanding, it is suggested that you place a "&" |
849 | next to the variable name and away from the variable type), and place a |
850 | "*" near the variable type, but away from the variable name (as in the |
360e660c |
851 | call to foo above). By doing so, it is easy to understand exactly what |
852 | will be passed to the C function -- it will be whatever is in the "last |
853 | column". |
4633a7c4 |
854 | |
c07a80fd |
855 | You should take great pains to try to pass the function the type of variable |
856 | it wants, when possible. It will save you a lot of trouble in the long run. |
4633a7c4 |
857 | |
360e660c |
858 | =head2 The Argument Stack |
4633a7c4 |
859 | |
c07a80fd |
860 | If we look at any of the C code generated by any of the examples except |
861 | example 1, you will notice a number of references to ST(n), where n is |
360e660c |
862 | usually 0. "ST" is actually a macro that points to the n'th argument |
863 | on the argument stack. ST(0) is thus the first argument on the stack and |
864 | therefore the first argument passed to the XSUB, ST(1) is the second |
865 | argument, and so on. |
4633a7c4 |
866 | |
beb31b0b |
867 | When you list the arguments to the XSUB in the .xs file, that tells B<xsubpp> |
c07a80fd |
868 | which argument corresponds to which of the argument stack (i.e., the first |
869 | one listed is the first argument, and so on). You invite disaster if you |
870 | do not list them in the same order as the function expects them. |
4633a7c4 |
871 | |
360e660c |
872 | The actual values on the argument stack are pointers to the values passed |
873 | in. When an argument is listed as being an OUTPUT value, its corresponding |
874 | value on the stack (i.e., ST(0) if it was the first argument) is changed. |
875 | You can verify this by looking at the C code generated for Example 3. |
876 | The code for the round() XSUB routine contains lines that look like this: |
877 | |
878 | double arg = (double)SvNV(ST(0)); |
879 | /* Round the contents of the variable arg */ |
880 | sv_setnv(ST(0), (double)arg); |
881 | |
882 | The arg variable is initially set by taking the value from ST(0), then is |
883 | stored back into ST(0) at the end of the routine. |
884 | |
beb31b0b |
885 | XSUBs are also allowed to return lists, not just scalars. This must be |
886 | done by manipulating stack values ST(0), ST(1), etc, in a subtly |
887 | different way. See L<perlxs> for details. |
888 | |
889 | XSUBs are also allowed to avoid automatic conversion of Perl function arguments |
890 | to C function arguments. See L<perlxs> for details. Some people prefer |
891 | manual conversion by inspecting C<ST(i)> even in the cases when automatic |
892 | conversion will do, arguing that this makes the logic of an XSUB call clearer. |
893 | Compare with L<"Getting the fat out of XSUBs"> for a similar tradeoff of |
894 | a complete separation of "Perl glue" and "workhorse" parts of an XSUB. |
895 | |
896 | While experts may argue about these idioms, a novice to Perl guts may |
897 | prefer a way which is as little Perl-guts-specific as possible, meaning |
898 | automatic conversion and automatic call generation, as in |
899 | L<"Getting the fat out of XSUBs">. This approach has the additional |
900 | benefit of protecting the XSUB writer from future changes to the Perl API. |
901 | |
360e660c |
902 | =head2 Extending your Extension |
4633a7c4 |
903 | |
c07a80fd |
904 | Sometimes you might want to provide some extra methods or subroutines |
905 | to assist in making the interface between Perl and your extension simpler |
906 | or easier to understand. These routines should live in the .pm file. |
907 | Whether they are automatically loaded when the extension itself is loaded |
360e660c |
908 | or only loaded when called depends on where in the .pm file the subroutine |
4a4eefd0 |
909 | definition is placed. You can also consult L<AutoLoader> for an alternate |
360e660c |
910 | way to store and load your extra subroutines. |
4633a7c4 |
911 | |
360e660c |
912 | =head2 Documenting your Extension |
4633a7c4 |
913 | |
c07a80fd |
914 | There is absolutely no excuse for not documenting your extension. |
915 | Documentation belongs in the .pm file. This file will be fed to pod2man, |
360e660c |
916 | and the embedded documentation will be converted to the man page format, |
c07a80fd |
917 | then placed in the blib directory. It will be copied to Perl's man |
918 | page directory when the extension is installed. |
4633a7c4 |
919 | |
c07a80fd |
920 | You may intersperse documentation and Perl code within the .pm file. |
921 | In fact, if you want to use method autoloading, you must do this, |
922 | as the comment inside the .pm file explains. |
4633a7c4 |
923 | |
c07a80fd |
924 | See L<perlpod> for more information about the pod format. |
4633a7c4 |
925 | |
360e660c |
926 | =head2 Installing your Extension |
4633a7c4 |
927 | |
c07a80fd |
928 | Once your extension is complete and passes all its tests, installing it |
360e660c |
929 | is quite simple: you simply run "make install". You will either need |
c07a80fd |
930 | to have write permission into the directories where Perl is installed, |
931 | or ask your system administrator to run the make for you. |
4633a7c4 |
932 | |
360e660c |
933 | Alternately, you can specify the exact directory to place the extension's |
934 | files by placing a "PREFIX=/destination/directory" after the make install. |
935 | (or in between the make and install if you have a brain-dead version of make). |
936 | This can be very useful if you are building an extension that will eventually |
937 | be distributed to multiple systems. You can then just archive the files in |
938 | the destination directory and distribute them to your destination systems. |
939 | |
940 | =head2 EXAMPLE 5 |
941 | |
942 | In this example, we'll do some more work with the argument stack. The |
943 | previous examples have all returned only a single value. We'll now |
944 | create an extension that returns an array. |
945 | |
946 | This extension is very Unix-oriented (struct statfs and the statfs system |
947 | call). If you are not running on a Unix system, you can substitute for |
948 | statfs any other function that returns multiple values, you can hard-code |
949 | values to be returned to the caller (although this will be a bit harder |
950 | to test the error case), or you can simply not do this example. If you |
951 | change the XSUB, be sure to fix the test cases to match the changes. |
952 | |
953 | Return to the Mytest directory and add the following code to the end of |
954 | Mytest.xs: |
955 | |
956 | void |
957 | statfs(path) |
958 | char * path |
beb31b0b |
959 | INIT: |
360e660c |
960 | int i; |
961 | struct statfs buf; |
962 | |
963 | PPCODE: |
964 | i = statfs(path, &buf); |
965 | if (i == 0) { |
966 | XPUSHs(sv_2mortal(newSVnv(buf.f_bavail))); |
967 | XPUSHs(sv_2mortal(newSVnv(buf.f_bfree))); |
968 | XPUSHs(sv_2mortal(newSVnv(buf.f_blocks))); |
969 | XPUSHs(sv_2mortal(newSVnv(buf.f_bsize))); |
970 | XPUSHs(sv_2mortal(newSVnv(buf.f_ffree))); |
971 | XPUSHs(sv_2mortal(newSVnv(buf.f_files))); |
972 | XPUSHs(sv_2mortal(newSVnv(buf.f_type))); |
973 | XPUSHs(sv_2mortal(newSVnv(buf.f_fsid[0]))); |
974 | XPUSHs(sv_2mortal(newSVnv(buf.f_fsid[1]))); |
975 | } else { |
976 | XPUSHs(sv_2mortal(newSVnv(errno))); |
977 | } |
978 | |
979 | You'll also need to add the following code to the top of the .xs file, just |
980 | after the include of "XSUB.h": |
981 | |
982 | #include <sys/vfs.h> |
983 | |
984 | Also add the following code segment to test.pl while incrementing the "1..9" |
985 | string in the BEGIN block to "1..11": |
986 | |
987 | @a = &Mytest::statfs("/blech"); |
988 | print ((scalar(@a) == 1 && $a[0] == 2) ? "ok 10\n" : "not ok 10\n"); |
989 | @a = &Mytest::statfs("/"); |
990 | print scalar(@a) == 9 ? "ok 11\n" : "not ok 11\n"; |
991 | |
992 | =head2 New Things in this Example |
993 | |
994 | This example added quite a few new concepts. We'll take them one at a time. |
995 | |
996 | =over 4 |
997 | |
998 | =item * |
999 | |
beb31b0b |
1000 | The INIT: directive contains code that will be placed immediately after |
1001 | the argument stack is decoded. C does not allow variable declarations at |
1002 | arbitrary locations inside a function, |
360e660c |
1003 | so this is usually the best way to declare local variables needed by the XSUB. |
beb31b0b |
1004 | (Alternatively, one could put the whole C<PPCODE:> section into braces, and |
1005 | put these declarations on top.) |
360e660c |
1006 | |
1007 | =item * |
1008 | |
1009 | This routine also returns a different number of arguments depending on the |
1010 | success or failure of the call to statfs. If there is an error, the error |
1011 | number is returned as a single-element array. If the call is successful, |
1012 | then a 9-element array is returned. Since only one argument is passed into |
1013 | this function, we need room on the stack to hold the 9 values which may be |
1014 | returned. |
1015 | |
1016 | We do this by using the PPCODE: directive, rather than the CODE: directive. |
beb31b0b |
1017 | This tells B<xsubpp> that we will be managing the return values that will be |
360e660c |
1018 | put on the argument stack by ourselves. |
1019 | |
1020 | =item * |
1021 | |
1022 | When we want to place values to be returned to the caller onto the stack, |
1023 | we use the series of macros that begin with "XPUSH". There are five |
1024 | different versions, for placing integers, unsigned integers, doubles, |
1025 | strings, and Perl scalars on the stack. In our example, we placed a |
beb31b0b |
1026 | Perl scalar onto the stack. (In fact this is the only macro which |
1027 | can be used to return multiple values.) |
360e660c |
1028 | |
1029 | The XPUSH* macros will automatically extend the return stack to prevent |
1030 | it from being overrun. You push values onto the stack in the order you |
1031 | want them seen by the calling program. |
1032 | |
1033 | =item * |
1034 | |
1035 | The values pushed onto the return stack of the XSUB are actually mortal SV's. |
1036 | They are made mortal so that once the values are copied by the calling |
1037 | program, the SV's that held the returned values can be deallocated. |
1038 | If they were not mortal, then they would continue to exist after the XSUB |
1039 | routine returned, but would not be accessible. This is a memory leak. |
1040 | |
beb31b0b |
1041 | =item * |
1042 | |
1043 | If we were interested in performance, not in code compactness, in the success |
1044 | branch we would not use C<XPUSHs> macros, but C<PUSHs> macros, and would |
1045 | pre-extend the stack before pushing the return values: |
1046 | |
1047 | EXTEND(SP, 9); |
1048 | |
1049 | The tradeoff is that one needs to calculate the number of return values |
1050 | in advance (though overextending the stack will not typically hurt |
1051 | anything but memory consumption). |
1052 | |
1053 | Similarly, in the failure branch we could use C<PUSHs> I<without> extending |
1054 | the stack: the Perl function reference comes to an XSUB on the stack, thus |
1055 | the stack is I<always> large enough to take one return value. |
1056 | |
360e660c |
1057 | =back |
1058 | |
1059 | =head2 EXAMPLE 6 (Coming Soon) |
1060 | |
1061 | Passing in and returning references to arrays and/or hashes |
1062 | |
1063 | =head2 EXAMPLE 7 (Coming Soon) |
1064 | |
1065 | XPUSH args AND set RETVAL AND assign return value to array |
1066 | |
1067 | =head2 EXAMPLE 8 (Coming Soon) |
1068 | |
1069 | Setting $! |
1070 | |
1071 | =head2 EXAMPLE 9 (Coming Soon) |
1072 | |
1073 | Getting fd's from filehandles |
1074 | |
1075 | =head2 Troubleshooting these Examples |
1076 | |
1077 | As mentioned at the top of this document, if you are having problems with |
1078 | these example extensions, you might see if any of these help you. |
1079 | |
1080 | =over 4 |
1081 | |
1082 | =item * |
1083 | |
1084 | In versions of 5.002 prior to the gamma version, the test script in Example |
1085 | 1 will not function properly. You need to change the "use lib" line to |
1086 | read: |
1087 | |
1088 | use lib './blib'; |
1089 | |
1090 | =item * |
1091 | |
1092 | In versions of 5.002 prior to version 5.002b1h, the test.pl file was not |
1093 | automatically created by h2xs. This means that you cannot say "make test" |
1094 | to run the test script. You will need to add the following line before the |
1095 | "use extension" statement: |
1096 | |
1097 | use lib './blib'; |
1098 | |
1099 | =item * |
1100 | |
1101 | In versions 5.000 and 5.001, instead of using the above line, you will need |
1102 | to use the following line: |
1103 | |
1104 | BEGIN { unshift(@INC, "./blib") } |
1105 | |
1106 | =item * |
1107 | |
1108 | This document assumes that the executable named "perl" is Perl version 5. |
1109 | Some systems may have installed Perl version 5 as "perl5". |
1110 | |
1111 | =back |
1112 | |
1113 | =head1 See also |
4633a7c4 |
1114 | |
c07a80fd |
1115 | For more information, consult L<perlguts>, L<perlxs>, L<perlmod>, |
1116 | and L<perlpod>. |
4633a7c4 |
1117 | |
360e660c |
1118 | =head1 Author |
4633a7c4 |
1119 | |
9607fc9c |
1120 | Jeff Okamoto <F<okamoto@corp.hp.com>> |
4633a7c4 |
1121 | |
c07a80fd |
1122 | Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig, |
1123 | and Tim Bunce. |
4633a7c4 |
1124 | |
c07a80fd |
1125 | =head2 Last Changed |
4633a7c4 |
1126 | |
beb31b0b |
1127 | 1999/11/30 |