view release on metacpan or  search on metacpan

lib/perlxstut.pod  view on Meta::CPAN

In this example, we'll do some more work with the argument stack.  The
previous examples have all returned only a single value.  We'll now
create an extension that returns an array.

This extension is very Unix-oriented (struct statfs and the statfs system
call).  If you are not running on a Unix system, you can substitute for
statfs any other function that returns multiple values, you can hard-code
values to be returned to the caller (although this will be a bit harder
to test the error case), or you can simply not do this example.  If you
change the XSUB, be sure to fix the test cases to match the changes.

Return to the Mytest directory and add the following code to the end of
Mytest.xs:

	void
	statfs(path)
		char *  path
	    INIT:
		int i;
		struct statfs buf;

	    PPCODE:
		i = statfs(path, &buf);
		if (i == 0) {
			XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
			XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
			XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
			XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
			XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
			XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
			XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
		} else {
			XPUSHs(sv_2mortal(newSVnv(errno)));
		}

You'll also need to add the following code to the top of the .xs file, just
after the include of "XSUB.h":

	#include <sys/vfs.h>

Also add the following code segment to Mytest.t while incrementing the "9"
tests to "11":

    my @a;

	@a = Mytest::statfs("/blech");
	ok( scalar(@a) == 1 && $a[0] == 2 );

	@a = Mytest::statfs("/");
	is( scalar(@a), 7 );

=head2 New Things in this Example

This example added quite a few new concepts.  We'll take them one at a time.

=over 4

=item *

The INIT: directive contains code that will be placed immediately after
the argument stack is decoded.  C does not allow variable declarations at
arbitrary locations inside a function,
so this is usually the best way to declare local variables needed by the XSUB.
(Alternatively, one could put the whole C<PPCODE:> section into braces, and
put these declarations on top.)

=item *

This routine also returns a different number of arguments depending on the
success or failure of the call to statfs.  If there is an error, the error
number is returned as a single-element array.  If the call is successful,
then a 7-element array is returned.  Since only one argument is passed into
this function, we need room on the stack to hold the 7 values which may be
returned.

We do this by using the PPCODE: directive, rather than the CODE: directive.
This tells B<xsubpp> that we will be managing the return values that will be
put on the argument stack by ourselves.

=item *

When we want to place values to be returned to the caller onto the stack,
we use the series of macros that begin with "XPUSH".  There are five
different versions, for placing integers, unsigned integers, doubles,
strings, and Perl scalars on the stack.  In our example, we placed a
Perl scalar onto the stack.  (In fact this is the only macro which
can be used to return multiple values.)

The XPUSH* macros will automatically extend the return stack to prevent
it from being overrun.  You push values onto the stack in the order you
want them seen by the calling program.

=item *

The values pushed onto the return stack of the XSUB are actually mortal SV's.
They are made mortal so that once the values are copied by the calling
program, the SV's that held the returned values can be deallocated.
If they were not mortal, then they would continue to exist after the XSUB
routine returned, but would not be accessible.  This is a memory leak.

=item *

If we were interested in performance, not in code compactness, in the success
branch we would not use C<XPUSHs> macros, but C<PUSHs> macros, and would
pre-extend the stack before pushing the return values:

	EXTEND(SP, 7);

The tradeoff is that one needs to calculate the number of return values
in advance (though overextending the stack will not typically hurt
anything but memory consumption).

Similarly, in the failure branch we could use C<PUSHs> I<without> extending
the stack: the Perl function reference comes to an XSUB on the stack, thus
the stack is I<always> large enough to take one return value.

=back

=head2 EXAMPLE 6

In this example, we will accept a reference to an array as an input