ExtUtils-ParseXS
view release on metacpan or search on metacpan
lib/perlxs.pod view on Meta::CPAN
| "PROTOTYPES:" enable
| "VERSIONCHECK:" enable
| "FALLBACK:" ("TRUE" | "FALSE" | "UNDEF")
| "INCLUDE:" [foo.xs]
| "INCLUDE_COMMAND:" [... some command line ...]
| "REQUIRE:" [1.23] // min xsubpp version
| "BOOT:"
code_block
| "TYPEMAP: <<"[EOF]
// Heredoc with typemap declarations.
[EOF]
enable = ( "ENABLE" | "DISABLE" )
code_block = // Lines of C and/or blank lines terminated by the
// next keyword or XSUB start. POD is stripped.
xsub = blank_line // not *always* necessary
xsub_decl
( cases | xbody )
xsub_decl = return_type
xsub_name "(" parameters ")" "const" ?
return_type = "NO_OUTPUT" ? "extern \"C\"" ? "static" ? C_type
C_type = [const char *] // etc: any valid C type
C_expression = [foo(ix) + 1] // etc: any valid C expression
xsub_name = [foo] | [X::Y::foo] // simple name or C++ name
parameters = empty
| parameter ( "," parameter )*
empty = /\s*/
parameter = (
in_out_decl ?
C_type ?
/\w+/ // variable name
// Default or optional value:
( "=" ( C_expression | "NO_INIT" ) )?
// Pseudo-param: foo must match another param name:
| C_type "length(" [foo] ")"
| "..."
)
in_out_decl = "IN" | "OUT" | "IN_OUT" | "OUTLIST" | "IN_OUTLIST"
cases = (
"CASE:" ( C_expression | empty )
xbody
)+
xbody = implicit_input ?
xbody_input_part *
xbody_init_part *
xbody_code_part
xbody_output_part * // Not after PPCODE.
xbody_cleanup_part * // Not after PPCODE.
implicit_input = ( blank_line | input_line )+
xbody_input_part =
"INPUT:" ( blank_line | input_line )*
| "PREINIT:"
code_block
| xbody_generic_key
| c_args
| interface_macro
| "SCOPE:" enable // Only in xsubpp 3.58 onwards.
input_line = C_type
"&" ?
/\w+/ // variable name
// Optional initialiser:
(
( "=" | ";" ) "NO_INIT"
|
// Override or add to the default typemap.
// The expression is eval()ed as a
// double-quotish string.
"=" [ a_typemap_override($arg) ]
|
("+" | ";") [ a_deferred_initialiser($arg) ]
)?
";" ?
xbody_init_part = "INIT:"
code_block
| xbody_generic_key
| c_args
| interface
| interface_macro
xbody_code_part =
autocall
| "CODE:"
code_block
| "PPCODE:"
code_block
| // Only recognised if immediately following
// an INPUT section:
"NOT_IMPLEMENTED_YET:"
// Implicit call to wrapped library function.
autocall = empty
xbody_output_part =
xbody_postcall *
xbody_output *
xbody_postcall = "POSTCALL:"
code_block
| xbody_generic_key
xbody_output = "OUTPUT:"
( blank_line
| output_line
| "SETMAGIC:" enable
)*
| xbody_generic_key
// Variable name with optional expression which
// overrides the typemap
output_line = /\w+/ ( [ sv_setfoo(ST[0], RETVAL) ] )?
xbody_cleanup_part = "CLEANUP:"
code_block
| xbody_generic_key
// Text to use as the arguments for an autocall;
// may be spread over multiple lines:
c_args = "C_ARGS:" [foo, bar, baz]
// Comma-separated list of Perl subroutine names
// which use the XSUB, over one or more lines:
interface = "INTERFACE:" [foo, bar, Bar::baz]
interface_macro =
"INTERFACE_MACRO:"
[GET_MACRO_NAME]
[SET_MACRO_NAME] ?
// These can appear anywhere in an XSUB.
xbody_generic_key = pod
| alias
| "PROTOTYPE:" ( enable | [$$@] )
// Whitespace-separated list of overload types,
// over one or more lines:
| "OVERLOAD:" [ cmp eq <=> etc ]
// Whitespace-separated list of attribute names,
// over one or more lines:
| "ATTRS:" [foo bar baz]
alias = "ALIAS:"
lib/perlxs.pod view on Meta::CPAN
block of code, such as C<CODE:> or C<BOOT:>, which silently ignore the
rest of the first line. (Yes, this is a implementation flaw.)
It is best to include a blank line between each file-scoped item, and
before the start of each XSUB. While some items I<are> processed correctly
if they are on the line immediately preceding the start of an XSUB, the
parser is inconsistent in their handling.
An XSUB ends when C</\n\n\S/> is encountered: i.e. a blank line followed
by something on column one. (This is why it's recommended to indent
XSUB-scoped keywords.) If the thing at column one matches any of the items
which can appear in between XSUBs (such as file-scoped keywords) then it,
and any subsequent lines, are processed as such. Anything starting on
column one which isn't otherwise recognised, is interpreted as the first
line of the next XSUB definition. In particular it is interpreted as the
return type of the XSUB: this can lead to weird errors when something is
unexpectedly interpreted as the start of a new XSUB, such as C</* */>,
which isn't valid in the XS half of the file apart from within code
blocks.
Some multi-line keywords, such as C<C_ARGS>, are treated as just a single
uninterpreted multi-line string. Others, such as C<OUTPUT>, have a
specific per-line syntax, where each line within the section is parsed.
Finally, code blocks such as C<CODE> are just copied as-is to the output C
file (possibly sandwiched between C<#line> directives to ensure that
compiler error messages report from the correct location).
The XS parser doesn't recognise C comments, so don't use them apart from
in C code (e.g. not in an XSUB signature). More generally, the XS parser
doesn't understand C syntax or semantics; it just uses crude regexes to
parse the XS file. For example the parser can handle an XSUB declaration
like this:
int
foo(int a, char *b = "),")
Here, the parser just extracts out everything between (...) and splits on
commas, with just enough intelligence to ignore commas etc within matching
pairs of double-quotes. The parser doesn't understand C type declaration
syntax; for example it typically just extracts everything before what
appears to be a parameter name, and assumes that it must be the type. That
"type" will later be looked up in a typemap, and if no entry is found,
will only then raise an error. So it will fail to correctly parse the
following parameters:
int
foo(int a /* not-a-comment */, this is seen as a type!! b)
In addition, the XS parser has historically been very permissive, even to
the point of accepting nonsense as input. Since around F<xsubpp> releases
3.54-3.61, more things are likely to warn or raise errors during XS
parsing, rather than silently generating a non-compilable C code file.
As mentioned earlier, an XSUB definition typically starts with C</\n\n\S/>
and continues until the next C</\n\n\S/>. The XSUB definition consists of
a declaration, followed by an optional body. The declaration gives the
function's name, parameters and return type, and is intended to mimic a C
function declaration. It is usually two lines long.
The XSUB's body consists of a series of keywords. The main C code of an
XSUB is specified by a C<CODE> or C<PPCODE> section. In the absence of
this, a short body is generated automatically, which consists of a call to
a C function with the same name and arguments as the XSUB. In this way,
the XSUB becomes a short wrapper function between Perl and the C library
function, with the wrapper handling the conversion been Perl and C
arguments. This is referred to in this document as I<autocall>.
Other keywords can be used to modify the code generated for the XSUB, or
to alter how it is registered with the interpreter (e.g. adding
attributes).
So that is the basic structure of an XSUB. What a real XSUB looks like
will be covered later in L</The Anatomy of an XSUB>, but first a slight
digression follows.
=head2 Overview of how data is passed to and from an XSUB
This section contains a basic background on how XSUBs are invoked, what
their arguments consist of, and how XSUB arguments are passed to and from
Perl. It is essentially a summary of some relevant sections within
L<perlguts>; see that document for a more detailed exploration.
Note that most of the information in this section isn't needed to create
basic XSUBs; but for more complex needs or for debugging, it helps to
understand what's happening behind the scenes.
=head3 Perl OPs
(This next paragraph is definitely only for background on debugging.)
An C<OP> is a data structure within the perl interpreter. It is used to
hold the nodes within a tree structure created when the perl source is
compiled. It usually represents a single operation within the perl source,
such as an add, or a function call. The structure has various flags and
data, and a pointer to a C function (called the PP function) which is used
to implement the actions of that OP. The main loop of the perl interpreter
consists of calling the PP function associated with the current OP
(C<PL_op>) and then updating it, typically to C<< PL_op->op_next >>.
In particular, the C<OP_ENTERSUB> OP, via a call to C<pp_enterub()>,
performs (or at least starts) a function call, including any calls to XS
functions
=head3 SVs and the Perl interpreter's argument stack
Almost all runtime data within the Perl interpreter, including all Perl
variables, are stored in an I<SV> structure. These SVs can hold data of
many different types, including integers (IV - integer value), strings (PV
- pointer value), references (RV), arrays (AV), elements of arrays,
subroutines (CV - code value) etc. These will be discussed in more detail
below.
Perl has an I<argument> stack, which is a C array of SV pointers. Most of
the run-time actions of the PP functions consist of pushing SV pointers
onto the stack or popping them off and processing them. There is a
companion I<mark> stack, which is an array of integers which are argument
stack offsets. These marks serve to delineate the stack into frames.
Consider this subroutine call:
@a = foo(1, $x);
lib/perlxs.pod view on Meta::CPAN
The first few lines of code in the C function are standard boilerplate
added to all XSUBs. Note that the naming convention for Perl
interpreter macros is that ones starting with a C<d> are declarations; they
go in places where a variable can be declared, and typically declare one
or more variables and possibly their initialisations.
C<dVAR> is mostly a no-op; it used to be needed for some obscure Perl
interpreter configurations and is still emitted for
backwards compatibility.
C<dXSARGS> pops one index off the mark stack and sets up some auto
variables to allow the arguments on the stack to be accessed:
specifically, the variable C<items> is declared, which indicates how many
arguments were passed, and some hidden variables are also declared which
are used by the macro C<ST(n)> to retrieve a pointer to argument C<n> from
the stack (counting from 0). The stack pointer is not actually decremented
yet.
For a generic list-processing XSUB, these argument-accessing variables and
macros may be used directly. But more commonly, for an XSUB which has a
fixed signature (as in the example above), the parser will declare an auto
C variable for each parameter, and (using the system or a user typemap)
assign them values extracted from C<ST(0)> etc. It will also declare a
variable called C<RETVAL> with the XSUB's return type (unless that is
C<void>), which is typically assigned to by the coder and then whose value
is automatically returned. Continuing the example above, the generated
code for the input part of the XSUB is similar to:
{
long z = ...;
short RETVAL;
int a = (int)SvIV(ST(0));
char *b;
if (items < 2)
b = "";
else
b = (char *)SvPV_nolen(ST(1));
This consists of declarations for C<a>, C<b>, C<z> and C<RETVAL>, plus
code to initialise them. The part of the code which extracts a value from
an SV on the stack, such as C<(int)SvIV(ST(0))>, is derived from a typemap
entry. For a simple entry such the one for C<a>, the code may be added as
part of the declaration of the variable itself; otherwise the
initialisation may be done as a separate statement after all the variable
declarations (such as for C<b>).
Variable declarations appear in the order they appear in C<INPUT> and
C<PREINIT> blocks, followed by C<RETVAL> and then any parameters defined
completely within the signature (i.e. which don't use an C<INPUT> section
to specify their type).
Note that C<INPUT> sections are generally obsolete these days, and
C<PREINIT> is rarely needed. Perls before 5.36 used C89 compiler
semantics, which didn't allow variable declarations after statements. CPAN
modules, depending on if/how they set compiler flags, may still default
to C89. To work around this, the C<PREINIT> keyword allows you to inject
additional variable declaration code early in the function.
Following on from the input part, the main body of the function is output;
this is copied exactly as-is from the C<CODE> or C<PPCODE> section, if
present. If neither is present, the parser will assume that this XSUB is
just wrapping a C library function of the same name as the XSUB, and will
automatically generate some code like the following:
RETVAL = baz(a, b);
The C<INIT> and C<POSTCALL> keywords may be used to add code just before
and after the main code; typically only useful for autocall.
C<PPCODE> is the same as C<CODE> except that after argument processing,
the stack pointer is reset to the base of the frame, and the coder becomes
responsible for pushing any return values onto the stack. No further
keywords can follow C<PPCODE>. This is typically used for XSUBs which
need to return a list or have other complex requirements beyond just
returning a single value.
For C<CODE> and autocall, unless the return type is void, the parser will
generate code to return the value of C<RETVAL>. This is automatic in the
case of autocall, but for C<CODE> you have to ask the parser to do so
with C<OUTPUT: RETVAL>. The code generated in either case may look
something like
{
SV *RETVALSV = sv_newmortal();
sv_setiv(RETVALSV, (IV)RETVAL);
ST(0) = RETVALSV;
}
A temporary SV will be created, set to the value of C<RETVAL> (again,
using a typemap template), then placed on the stack. In practice, various
optimisations may be used; in particular, the C<PADTMP> target SV which is
attached to the calling C<OP_ENTERSUB> may be used instead of allocating
and freeing an SV for each call, as explained earlier.
XSUB parameters declared as C<OUT> or C<OUTLIST> will cause additional
output code to be generated which respectively: updates the value of one
of the passed arguments; or pushes the value of that parameter onto the
stack (in addition to C<RETVAL>).
Finally, (apart from C<PPCODE>), a macro like this is added to the end of
the C function:
XSRETURN(1);
This resets the stack pointer to one above the base of the frame (so the
top item on the stack is C<ST(0)>), then does C<return>.
For a C<void> XSUB, C<XSRETURN_EMPTY> is used instead.
=head2 Returning Values from an XSUB
An XSUB's declared return type is typically a C type such as C<int> or
C<char*>. XS is very good at automating this common case of returning a
single C-ish value: behind the scenes it creates a temporary SV; then,
using an appropriate typemap template, sets that SV to the value of
C<RETVAL> and returns that SV on the stack.
But sometimes you want to return a Perl-ish value rather than a C-ish
value, for example, Perl's undef value or a Perl array reference. Or you
may want to return multiple values, or update one of the passed
arguments. The following subsections describe various such cases.
Note that XSUBs are somewhat like Perl lvalue subs, in that they return
the actual SV to the caller, while normal Perl subs return a temporary
copy of each return value. When returning a C value like C<int> this
doesn't matter, since the XSUB is returning a temporary SV anyway; but
when returning your own SV, it could in theory make a visible difference.
For example,
sub foo { $_[0]++ }
foo(an_xsub_which_returns_element_0_of_an_array(\@a));
would increment C<$a[0]>.
=head3 Returning undef / TRUE / FALSE / empty list
Sometimes you need to return an undefined value, e.g. to indicate failure.
It's possible to return early from a CODE block with an undefined value,
bypassing the normal creation of a temporary SV and the setting of its
value. For example:
int
file_size(char *filename)
CODE:
RETVAL = file_size(filename);
if (RETVAL == -1)
XSRETURN_UNDEF;
OUTPUT:
RETVAL
The C<XSRETURN_UNDEF> macro causes the address of the special Perl SV
C<PL_sv_undef> to be stored at C<ST(0)> (which is the same value that the
Perl function C<undef> returns), and then makes the XSUB return
immediately.
If using autocall, then you can instead return early in a C<POSTCALL>
section:
int
file_size(char *filename)
lib/perlxs.pod view on Meta::CPAN
However, these aren't allowed directly on the argument stack. You are
supposed to instead return a I<reference> to the AV: a bit like a Perl sub
returning C<\@foo>.
The standard typemaps can create this reference for you automatically. So
for example an XSUB with a return type of C<AV*> will actually create and
return an RV scalar which references the AV in C<RETVAL>. So the XS
equivalent of Perl's C<return [8,9]> might be:
AV *
array89()
CODE:
RETVAL = newAV();
/* see text below for why this line is needed */
sv_2mortal((SV*)RETVAL);
av_store(RETVAL, 0, newSViv(8));
av_store(RETVAL, 1, newSViv(9));
OUTPUT:
RETVAL
Note that the C<RETVAL> variable is declared as type C<AV*>, but what is
actually returned to the caller is a temporary SV which is a reference to
C<RETVAL>. The standard output typemap template for the C<AV*> type looks
like:
$arg = newRV((SV*)$var);
This means it creates a new RV which refers to to the AV. Because of the
rule for C<$arg = ...> typemaps, the RV will be correctly mortalised
before being returned. However, the C<newRV()> function increments the
reference count of the thing being referred to (the C<RETVAL> AV in this
case). Since the AV has just been created by C<newAV()> with a reference
count one too high, it will leak. This why the C<sv_2mortal()> is
required. Conversely for a pre-existing AV, the mortalisation isn't
required.
Since F<xsubpp> 3.06, there are a set of alternative XS types which can be
used for AVs etc which I<don't> increment the reference count of the AV
when being pointed to from the new RV. These can be enabled by mapping the
C<AV*> etc C types to these new XS types:
TYPEMAP: <<EOF
AV* T_AVREF_REFCOUNT_FIXED
HV* T_HVREF_REFCOUNT_FIXED
CV* T_CVREF_REFCOUNT_FIXED
SVREF T_SVREF_REFCOUNT_FIXED
EOF
Or alternatively you could just declare the return type as C<SV*> and
handle the RV generation yourself:
SV *
create_array_ref()
CODE:
RETVAL = newRV_noinc((SV*)newAV());
OUTPUT:
RETVAL
If instead you want to return a flattened array (the equivalent of Perl's
C<return @a>) then you would have to push the elements of the array
individually onto the stack in a C<PPCODE> block. See L</Returning a
list> below.
Finally, the C C<SVREF> type in the standard typemap is a way of creating
and returning a I<reference> to a scalar. This is in contrast to the
C<SV*> type, which just returns a scalar.
Note that unlike C<SV> etc, C<SVREF> isn't a standard built-in Perl type:
it exists purely as an entry in a typemap. So In this case you have to
tell the C compiler that C<SVREF> is just another name for C<SV*>:
typedef SV *SVREF;
Then in an XSUB like
SVREF
foo()
CODE:
RETVAL = newSViv(9);
sv_2mortal(RETVAL);
OUTPUT:
RETVAL
C<RETVAL> will be declared with type C<SVREF> (hence the need for the
typedef above), and the XSUB will return a reference the C<RETVAL> SV.
This XSUB is the equivalent of the perl C<my $x = 9; return \$x>.
=head3 Updating arguments and returning multiple values.
By using the C<IN_OUT> and similar parameter modifiers, XS provides
limited support for returning extra values in addition to (or instead of)
C<RETVAL>, either by updating the values of passed arguments (C<OUT>), or
by returning some of the parameters (and pseudo-parameters) as extra
return values (C<OUTLIST>). For returning an arbitrary list of values, see
the next section.
Here are a couple of simple XS examples with their approximate perl
equivalents:
# Update a passed argument
void sub inc9 {
inc9(IN_OUT int i) my $i = $_[0];
CODE: $i += 9;
i += 9 $_[0] = $i;
}
# Return (2*$i, 3*$i)
void sub mul23 {
mul23(int i, \ my $i = $_[0];
OUTLIST int x, \ my ($x, $y);
OUTLIST int y) $x = $i * 2;
CODE $y = $i * 3;:
x = i * 2; return $x, $y;
y = i * 3; }
See L</"Updating and returning parameter values: the IN_OUT etc keywords">
for the full details,
=head3 Returning a list
If you want to return a list, i.e. an arbitrary number of items on the
stack, you generally have to forgo the convenience of some of the
boilerplate code generated by XS, which is biased towards returning a
single value. Instead you will have to create and push the SVs yourself.
The L<PPCODE|/The PPCODE: Keyword> keyword is specifically intended for
this purpose. Here is a simple example which does the same as the
Perl-level C<return 1..$n>:
void
one_to_n(int n)
PPCODE:
{
int i;
if (n < 1)
Perl_croak_nocontext(
"one_to_n(): argument %d must be >= 1", n);
EXTEND(SP, n);
for (i = 1; i <= n; i++)
mPUSHi(i);
}
The C<PPCODE> keyword causes the argument stack pointer to be initially
reset to the base of the frame (discarding any passed arguments), and
suppresses any automatic return code generation. The return type of the
XSUB is ignored, except that declaring it C<void> suppresses the
declaration of a C<RETVAL> variable.
The C<EXTEND()> macro makes sure that there are at least that many free
slots on the stack (its first argument should always be C<SP>). The
C<mPUSHi()> macro creates a new SV, mortalises it, sets its value to the
integer C<i>, and pushes it on the stack.
Here's another example, which flattens the array passed as an argument:
the equivalent of this Perl:
sub flatten { my $aref = $_[0]; @$aref: }
In this example, the SVs being pushed aren't freshly created with a
reference count one too high, so don't need mortalising.
void
flatten(AV *av)
PPCODE:
{
int i;
int max_ix = AvFILL(av);
SV **svp;
EXTEND(SP, max_ix + 1);
for (i = 0; i <= max_ix; i++) {
svp = av_fetch(av, i, 0);
PUSHs(svp ? *svp : &PL_sv_undef);
}
}
This function actually expects to be passed a I<reference> to an array:
the input typemap entry for C<AV*> automatically takes care of
dereferencing the argument and croaking if it's not actually a reference.
The C<PUSHs()> macro simply pushes an SV onto the stack, without any
mortalising or copying. Any "holes" in the array are filled with undefs.
Note that there is a C<XPUSHs()> macro which combines a push with an
C<EXTEND(1)>; but if you know at the start how many items are to be
pushed, it is more efficient to do a single large extend first.
Note also that there is always guaranteed to be one allocated slot on the
stack when an XSUB is called, even if it has no arguments. So for the
particular case of returning a single value, no extend is necessary.
=head2 Bootstrapping
In addition to the C<XS_Foo__Bar_baz()> C function generated for each XSUB
declaration, a C<boot_Foo__Bar()> C function is also automatically
generated, one for each XS file. This XSUB function is called once when
the module is first loaded. For each declared XSUB in the file, a line
similar to the following is added to the boot function:
newXS("Foo::Bar::baz", XS_Foo__Bar_baz);
(the exact details of the code will vary across releases and
configurations). This call creates a CV, flags it as being an XSUB, adds
a pointer from it to C<XS_Foo__Bar_baz()>, then adds the CV to the
C<*FOO::Bar::baz> typeglob in the Perl interpreter's symbol table. It is
the XS equivalent of the Perl-level
*FOO::Bar::baz = sub { ... }
For some XSUBs, additional lines may be added by the parser to the boot
XSUB to handle things like aliases or overloading.
You can add your own additional lines to the boot XSUB using the C<BOOT>
keyword.
A typical Perl module like F<Foo/Bar.pm> should have code in it similar
to:
package Foo::Bar;
our $VERSION = '1.01';
require XSLoader;
XSLoader::load();
This causes the F<Bar.so> or F<Bar.dll> file to be dynamically linked in
and then the C<boot_Foo__Bar()> function to be called. This boilerplate
code is typically created automatically with F<h2xs> when you first create
lib/perlxs.pod view on Meta::CPAN
<< FOO
<< 'FOO'
<< "FOO"
where C<FOO> can be just about any sequence of characters, which must be
matched at the start of a subsequent line.
See L</Using Typemaps> and L<perlxstypemap> for more details on writing
typemaps.
=head3 The BOOT: Keyword
BOOT:
# Print a message when the module is loaded
printf("Hello from the bootstrap!\n");
The C<BOOT> keyword is used to add code to the extension's bootstrap
function. This function is generated by the XS parser and normally holds
the statements necessary to register any XSUBs with Perl. It is usually
called once, at C<use Foo::Bar> time.
This keyword should appear on a line by itself. All subsequent lines will
be interpreted as lines of C code to pass through, including C
preprocessor directives, but excluding POD and C<#> comments; until the
next keyword or possible start of a new XSUB (C</\n\n\S/>).
=head3 The FALLBACK: Keyword
MODULE = Foo PACKAGE = Foo::Bar
FALLBACK: TRUE | FALSE | UNDEF
Since F<xsubpp> 2.09_01.
It defaults to C<UNDEF> for each package. It sets the default fallback
handling behaviour for overloaded methods in the current package (i.e.
C<Foo:Bar> in the example above). It is analogous to the Perl-level:
package Foo::Bar;
use overload "fallback" => 1 | 0 | undef;
It only has any effect if there ends up being at least one XSUB in the
current package with the L<OVERLOAD|/The OVERLOAD: Keyword> keyword
present. See L<overload/fallback> for more details.
=head2 The Structure of an XSUB
Following any file-scoped XS keywords and directives, an XSUB may appear.
The start of an XSUB is usually indicated by a blank line followed by
something starting on column one which isn't otherwise recognised as an
XSUB keyword or file-scoped directive.
An XSUB definition consists of a declaration (typically two lines),
followed by an optional body. The declaration specifies the XSUB's name,
parameters and return type. The body consists of sections started by
keywords, which may specify how its parameters and any return value
should be processed, and what the main C code body of the XSUB consists
of. Other keywords can change the behaviour of the XSUB, or affect how it
is registered with Perl, e.g. with extra named aliases. In the absence of
an explicit main C code body specified by the C<CODE> or C<PPCODE>
keywords, the parser will generate a body automatically; this is referred
to as L<autocall|/"Auto-calling a C function"> in this document.
Nothing can appear between keyword sections apart from POD, XS comments,
and trailing blank lines, all of which are stripped out before the main
parsing takes place. Anything else will either raise an error, or be
interpreted as the start of a new XSUB.
An XSUB's body can be thought of as having up to five parts. These are, in
order of appearance, the L<Input|/"The XSUB Input Part">, L<Init|/"The
XSUB Init Part">, L<Code|/"The XSUB Code Part">, L<Output|/"The XSUB
Output Part"> and L<Cleanup|/"The XSUB Cleanup Part"> parts. There is no
formal syntax to define this structure; it's just an understanding that
certain keywords may only appear in certain parts and thus may only appear
after certain other keywords etc.
=head2 An XSUB Declaration
# A simple declaration:
int
foo1(int i, char *s)
# All on one line; plus a default parameter value:
int foo2(int i, char *s = "")
# Complex parameters; plus variable argument count:
int
foo3(OUT int i, IN_OUTLIST char *s, STRLEN length(s), ...)
# No automatic argument processing:
void
foo4(...)
PPCODE:
# C++ method; plus various return type qualifiers:
NO_OUTPUT extern "C" static int
X::Y::foo5(int i, char *s) const
An XSUB declaration consists of a return type, name, parameters, and
optional C<NO_OUTPUT>, C<extern "C">, C<static> and C<const> keywords.
=head3 An XSUB's return type and the NO_OUTPUT keyword
The return type can be any valid C type, including C<void>. When non-void,
it serves two purposes. First, it causes a C auto variable of that type
to be declared, called C<RETVAL>. Second, it (usually) makes the XSUB
return a single SV whose value is set to C<RETVAL>'s value at the time of
return. In addition, a non-void autocall XSUB will call the underlying C
library function and assign its return value to C<RETVAL>.
In addition the return type can be a Perl package name; see
L</Fully-qualified type names and Perl objects> for details.
If the return type is prefixed with the C<NO_OUTPUT> keyword, then the
C<RETVAL> variable is still declared, but code to return its value is
suppressed. It is typically useful when making an autocall function
interface more Perl-like, especially when the C return value is just an
error condition indicator. For example,
NO_OUTPUT int
delete_file(char *name)
# implicit autocall code here: RETVAL = delete_file(name);
POSTCALL:
if (RETVAL != 0)
croak("Error %d while deleting file '%s'", RETVAL, name);
Here the generated XS function returns nothing on success, and will
C<die()> with a meaningful error message on error. The XSUB's return type
of C<int> is only meaningful for declaring C<RETVAL> and for doing the
autocall.
The return type can also include the C<extern "C"> and C<static>
modifiers, which if present must be in that order, and come between any
C<NO_OUTPUT> keyword and the return type. The C<extern> declaration must
be written exactly as shown, i.e. with a single space and with double
quotes around the C<C>. These two modifiers are mainly of use for XSUBs
written in C++. A C++ XSUB declaration is also allowed to have a trailing
C<const> keyword, which mimics the C++ syntax. See L</"Using XS With C++">
for more details.
=head3 An XSUB's name
The name of the XSUB is usually put on the line following the return type,
in which case it must be on column one. It is permissible for both the
type and name to be on the same line.
The name can be any valid Perl subroutine name. The C<PACKAGE> value from
the most recent C<MODULE> declaration is used to give the XSUB it's
fully-qualified Perl name.
If the name includes the package separator, C<::>, then it is treated as
lib/perlxs.pod view on Meta::CPAN
Each length parameter must match another parameter of the same name. That
parameter must be a string type (something which maps to the C<T_PV>
typemap type).
=back
=head3 Ellipsis: variable-length parameter lists
int
foo(char *s, ...)
An XSUB can have a variable-length parameter list by specifying an
ellipsis as the last parameter, similar to C function declarations. Its
main effect is to disable the error check for too many parameters. Any
declared parameters will still be processed as normal, but the programmer
will have to access any extra arguments manually, making use of the
C<ST(n)> macro to access the nth item on the stack, and the C<items>
variable, which indicates the total number of passed arguments, including
any fixed arguments. Note that C<ST(0)> is the first passed argument,
while the first ellipsis argument is C<ST(i)> where C<i> is the number of
fixed arguments preceding the ellipsis.
Note that currently XS doesn't provide any mechanism to autocall
variable-length C functions, so the ellipsis should only be used on XSUBs
which have a body.
For example, consider this Perl subroutine which returns the sum of all
of its arguments which are within a specified range:
sub minmax_sum {
my $min = shift;
my $max = shift;
my $RETVAL = 0;
$RETVAL += $_ for grep { $min <= $_ && $_ <= $max } @_;
return $RETVAL;
}
This XSUB provides equivalent functionality:
int
minmax_sum(int min, int max, ...)
CODE:
{
int i = 2; /* skip the two fixed arguments */
RETVAL = 0;
for (; i < items; i++) {
int val = (int)SvIV(ST(i));
if (min <= val && val <= max)
RETVAL += val;
}
}
OUTPUT:
RETVAL
It is possible to write an XSUB which both accepts and returns a list. For
example, this XSUB does the equivalent of the Perl C<map { $_*3 } ...>
void
triple(...)
PPCODE:
SP += items;
{
int i;
for (i = 0; i < items; i++) {
int val = (int)SvIV(ST(i));
ST(i) = sv_2mortal(newSViv(val*3));
}
}
Note that the L<PPCODE|/The PPCODE: Keyword> keyword, in comparison to
C<CODE>, resets the local copy of the argument stack pointer, and relies
on the coder to place any return values on the stack. The example above
reclaims the passed arguments by setting C<SP> back to the top of the
stack, then replaces the items on the stack one by one.
=head2 The XSUB Input Part
Following an XSUB's declaration part, the body of the XSUB follows. The
first part of the body is the I<input> part, and is mainly concerned with
declaring auto variables and assigning to them values extracted from the
passed parameters. The two main keywords associated with this activity are
L<PREINIT|/The PREINIT: Keyword> and L<INPUT|/The INPUT: Keyword>. The
first allows you to inject extra variable declaration lines, while the
latter used to be needed to specify the type of each parameter, but is now
mainly of historical interest. This is also the place for the rarely-used
L<SCOPE|/The SCOPE: Keyword and typemap entry> keyword.
Note that the keywords described in L<XSUB Generic Keywords> and L<Sharing
XSUB bodies> may also appear in this part, plus the L<C_ARGS|/The C_ARGS:
Keyword> and L<INTERFACE_MACRO|/The INTERFACE_MACRO: Keyword> keywords.
=head3 The PREINIT: Keyword
PREINIT:
int i;
char *prog_name = get_prog_name();
This keyword allows extra variables to be declared and possibly
initialised immediately before the declarations of auto variables
generated from any parameter declarations or C<INPUT> lines. Any lines
following C<PREINIT> until the next keyword (except POD and XS comments)
are copied out as-is to the C code file. Multiple C<PREINIT> keywords are
allowed.
It is sometimes needed because in traditional C, all variable
declarations must come before any statements. While this is no longer a
restriction in the perl interpreter source since Perl 5.36.0, the C
compiler flags used when compiling XS code may be different and so,
depending on the compiler, it may still be necessary to preserve the
correct ordering.
Any variable declarations generated by C<INPUT> and lines from C<PREINIT>
are output in the same order they appear in the XS source, followed by any
variable declarations generated from the XSUB's parameter declarations.
These may be followed by statements to initialise those those variables.
Thus, any variable declarations in a later C<INIT> or C<CODE> block may be
flagged as a declaration-after-statement.
C<PREINIT> code shouldn't assume that any variables declared earlier have
already been initialised; initialisation is deferred if the initialisation
code (typically obtained from a typemap) isn't of the simple C<type var =
init;> form, or has a default value.
For example:
void
foo(int i = 0)
PREINIT:
int j = 1;
CODE:
lib/perlxs.pod view on Meta::CPAN
the keyword). For the first, it may appear anywhere in the input part or
the XSUB. For the latter, it may appear anywhere in file scope, but due to
a long-standing parser bug, the keyword's state is reset at the start of
each XSUB, so it will only have any effect if it appears just before a
XSUB declaration and as part of the same paragraph (i.e. with no
intervening blank lines), such as in the example above. It will only
affect the single following XSUB.
The XSUB-scoped form has been available since F<xsubpp> 1.9506, but was
broken in release 2.21 and fixed in 3.58. The file-scoped form has been
available since 2.21.
To support potentially complex type mappings, if an C<INPUT> typemap entry
contains a code comment like C</* SCOPE */>, then scoping will be
automatically enabled for any XSUB which uses that typemap entry. This
currently only works for parameters whose type is specified using
old-style C<INPUT> lines rather than an ANSI-style declaration, i.e. not
for C<foo(int i)>. In fact, the XS parser, when looking for a SCOPE
comment in a typemap, is currently very lax: it's actually a
case-insensitive match of any code comment which contains the text "scope"
plus anything else. But you shouldn't rely on this; always use the form
shown here. Even better, just don't use it at all.
=head2 The XSUB Init Part
Following an XSUB's input part, an optional init part follows. This
consists solely of the C<INIT> keyword described below, plus the keywords
described in L<XSUB Generic Keywords> and L<Sharing XSUB bodies>, plus the
L<C_ARGS|/The C_ARGS: Keyword>.
=head3 The INIT: Keyword
The C<INIT> keyword allows arbitrary initialisation code to be inserted
after any variable declarations (and their initialisations), but before
the main body of code. It is primarily intended for use when the main body
is an autocall to a C function. For example these two XSUBs are
equivalent:
int
foo(int i)
INIT:
if (i < 0)
XSRETURN_UNDEF;
int
foo(int i)
CODE:
if (i < 0)
XSRETURN_UNDEF;
RETVAL = foo(i);
OUTPUT:
RETVAL
Any lines following C<INIT> until the next keyword (except POD and XS
comments) are copied out as-is to the C code file. Multiple C<INIT>
keywords are allowed.
=head2 The XSUB Code Part
Following an XSUB's optional init part, an optional code part follows. This
consists mainly of the C<CODE> or C<PPCODE> keywords, which provide the
code block for the main body of the XSUB. These two keywords are similar,
except that C<PPCODE> can be thought of as acting at a lower level; it
resets the stack pointer to the base of the stack frame and then relies on
the programmer to push any return values; whereas C<CODE> will (with
prompting) automatically generate code to return the value of C<RETVAL>.
There is also a rarely-used C<NOT_IMPLEMENTED_YET> keyword which generates
a body which croaks.
Only one of these keywords may appear in this part, and at most once; and
no other keywords are recognised in this part (although such keywords
could instead be processed in the tail or head of the preceding and
following init and output parts).
In the absence of any of those three keywords, the XS compiler will
generate an autocall: a call to the C function of the same name as the
XSUB.
=head3 Auto-calling a C function
In the absence of any explicit main body code via C<CODE>, C<PPCODE> or
C<NOT_IMPLEMENTED_YET>, the XS parser will generate a body for you
automatically (this is referred to as C<autocall> in this document). In
its most basic form, the parser assumes that the XSUB will be a simple
wrapper for a C function of the same name, with the same parameters and
return type as the XSUB. So for example, these two XSUB definitions are
equivalent, but the first is an autocall with less boilerplate needed:
int
foo(char *s, short flags)
int
foo(char *s, short flags)
CODE:
RETVAL = foo(s, flags);
OUTPUT:
RETVAL
Note that the XSUB C function and the wrapped C function are two
different entities; the first will have a name like C<XS_Foo__Bar_foo>;
when Perl code calls the 'Perl' function C<Foo::Bar::foo()>, behind the
scenes the Perl interpreter calls C<XS_Foo__Bar_foo()>, which extracts the
string and short int values from the two passed argument SVs, calls
C<foo()>, then stuffs its return value into an SV and returns that to the
Perl caller.
The two basic types of generated autocall code are:
foo(a, b, c);
RETVAL = foo(a, b, c);
depending on whether the XSUB is declared C<void> or not. The variables
passed to the function are usually just the names of the XSUB's
parameters, in the same order. Parameters with default values are
included, while ellipses are ignored. So for example
int
foo(int a, int b = 0, ...)
generates this autocall code:
RETVAL = foo(a, b);
There are various keywords which can be used to modify the basic behaviour
of an autocall.
=over
=item *
The L<PREFIX|/The MODULE Declaration> keyword, which allows wrapped C functions
which share a common prefix in their names to be mapped to perl functions
whose names don't have that prefix.
=item *
The
L<OUT|/"Updating and returning parameter values: the IN_OUT etc keywords">
etc parameter modifiers, which cause that parameter to be passed to the
autocalled function with a C<&> prefix, on the assumption that the
wrapped function expects a pointer and will update the location pointed
to.
=item *
The L<length(param_name)|/"The C<length(param_name)> pseudo-parameter">
pseudo-parameter, which allows the length of another parameter to be
passed as a separate argument to the wrapped function, even though it
isn't a parameter of the Perl function.
=item *
The L<C_ARGS|/"The C_ARGS: Keyword"> keyword, which allows the arguments
passed to the wrapped function to be completely overridden: handy when
arguments need to be skipped or reordered compared with the perl
function.
=item *
The L<INIT|/"The INIT: Keyword"> keyword, which allows code to be added
directly before the autocall.
=item *
The L<POSTCALL|/"The POSTCALL: Keyword"> keyword, which allows code to be
added directly after the autocall.
=item *
Support for L<C++|/"Using XS With C++"> XSUBs, which can (among other
things) modify the autocall into a C++ method call, e.g.
C<< THIS->foo(s,flags) >>.
=back
=head4 The C_ARGS: Keyword
void foo1(int a, int b, int c)
C_ARGS: b, a
void foo2(int a, int b)
C_ARGS: a < 0 ? 0 : a,
b,
0
Normally the arguments for an autocall are generated automatically, based
on the XSUB's parameter declarations. The C<C_ARGS> keyword allows you to
override this and manually specify the text that will be placed between
the parentheses in the autocall. This is useful when the ordering and
nature of parameters varies between Perl and C, without a need to write a
C<CODE> or C<PPCODE> section.
The C<C_ARGS> section consists of all lines of text until the next keyword
or to the end of the XSUB, and is used without modification (except that
any POD or XS comments will be stripped).
=head3 The CODE: Keyword
int
abs_double(int i)
CODE:
if (i < 0)
i = -i;
RETVAL = i * 2;
OUTPUT:
RETVAL
The C<CODE> keyword is the usual mechanism for providing your own code as
the main body of the XSUB. It is typically used when the XSUB, rather than
wrapping a library function, is providing general functionality which can
be more easily or efficiently implemented in C than in Perl.
Alternatively, it can still be used to wrap a library function for cases
which are too complex for autocall to handle.
Note that on entry to the C<CODE> block of code, the values of any passed
arguments will have been assigned to auto variables, but the original SVs
will still be on the stack and accessible via C<ST(i)> if necessary.
Similarly to autocall XSUBs, a C<RETVAL> variable is declared if the
return value of the XSUB is not C<void>. Unlike autocall, you have to
explicitly tell the XS compiler to generate code to return the value of
C<RETVAL>, by using the The L<OUTPUT|/"The OUTPUT: Keyword"> keyword.
(Requiring this was probably a bad design decision, but we're stuck with
it now.) Newer XS parsers will warn if C<RETVAL> is seen in the C<CODE>
section without a corresponding C<OUTPUT> section.
A C<CODE> XSUB will typically return just the C<RETVAL> value (or possibly
more items with the C<OUTLIST> parameter modifiers). To take complete
control over returning values, you can use the C<PPCODE> keyword instead.
Note that it is possible for a C<CODE> section to do this too, by doing its
own stack manipulation and then doing an C<XSRETURN(n)> to return directly
while indicating that there are C<n> items on the stack. This bypasses the
normal C<XSRETURN(1)> etc that the XS parser will have planted after the
C<CODE> lines. But it is usually cleaner to use C<PPCODE> instead.
Any lines following C<CODE> until the next keyword (except POD and XS
comments) are copied out as-is to the C code file. Multiple C<CODE>
keywords are not allowed.
=head3 The PPCODE: Keyword
# XS equivalent of: sub one_to_n { my $n = $_[0]; 1..$n }
void
one_to_n(int n)
PPCODE:
{
int i;
if (n < 1)
Perl_croak_nocontext(
"one_to_n(): argument %d must be >= 1", n);
EXTEND(SP, n);
for (i = 1; i <= n; i++)
mPUSHi(i);
}
The C<PPCODE> keyword is similar to the C<CODE> keyword, except that on
entry it resets the stack pointer to the base of the current stack frame,
and it doesn't generate any code to return C<RETVAL> or similar: pushing
return values onto the stack is left to the programmer. In this way it can
be viewed as a lower-level alternative to C<CODE>, when you want to take
full control of manipulating the argument stack. The "PP" in its name
stands for "PUSH/PULL", reflecting the low-level stack manipulation.
C<PPCODE> is typically used when you want to return several values or even
an arbitrary list, compared with C<CODE>, which normally returns just the
value of C<RETVAL>.
The C<PPCODE> keyword must be the last keyword in the XSUB. Any lines
following C<PPCODE> until the end of the XSUB (except POD and XS comments)
are copied out as-is to the C code file. Multiple C<PPCODE> keywords are
not allowed.
Typically you declare a C<PPCODE> XSUB with a return type of C<void>; any
other return type will cause a C<RETVAL> auto variable of that type to be
declared, which will be otherwise unused.
On entry to the C<PPCODE> block of code, the values of any declared
parameters arguments will have already been assigned to auto variables,
but the original SVs will still be on the stack and initially accessible
via C<ST(i)> if necessary. But the default assumption for a C<PPCODE>
block is that you have already finished processing any supplied arguments,
and that you want to push a number of return values onto the stack. The
simple C<one_to_n()> example shown above is based on that assumption. But
more complex strategies are possible.
There are basically two ways to access and manipulate the stack in a
C<PPCODE> block. First, by using the C<ST(i)> macro, to get, modify, or
replace the I<i>th item in the current stack frame, and secondly to push
(usually temporary) return values onto the stack. The first uses the
hidden C<ax> variable, which is set on entry to the XSUB, and is the index
of the base of the current stack frame. This remains unchanged throughout
execution of the XSUB. The second approach uses the local stack pointer,
C<SP> (more on that below), which on entry to the C<PPCODE> block points
to the base of the stack frame. Macros like C<mPUSHi()> store a temporary
SV at that location, then increment C<SP>. On return from a C<PPCODE>
XSUB, the current value of C<SP> is used to indicate to the caller how
many values are being returned.
In general these two ways of accessing the stack should not be mixed, or
confusion is likely to arise. The PUSH strategy is most useful when you
have no further use for the passed arguments, and just want to generate
and return a list of values, as in the C<one_to_n()> example above. The
C<ST(i)> strategy is better when you still need to access the passed
arguments. In the example below,
# XS equivalent of: sub triple { map { $_ * 3} @_ }
void
triple(...)
PPCODE:
SP += items;
{
int i;
for (i = 0; i < items; i++) {
int val = (int)SvIV(ST(i));
ST(i) = sv_2mortal(newSViv(val*3));
}
}
C<SP> is first incremented to reclaim the passed arguments which are still
on the stack; then one by one, each passed argument is retrieved, and then
each stack slot is replaced with a new mortal value. When the loop is
finished, the current stack frame contains a list of mortals, which is
then returned to the caller, with C<SP> indicating how many items are
returned. Note that in this example the C<SP += items> could have been
done at the end instead. However, if the code was doing a mixture of
updating the passed arguments I<and> pushing extra return values, then
setting it early (before the first push) would be important.
Before pushing return values onto the stack (or storing values at C<ST(i)>
locations higher than the number of passed arguments), it is necessary to
ensure there is sufficient space on the stack. This can be achieved either
through the C<EXTEND(SP, n)> macro as shown in the C<one_to_n()> example
above, or by using the 'X' variants of the push macros, such as
C<mXPUSHi()>, which can be used to check and extend the stack by one each
time. Doing a single C<EXTEND> in advance is more efficient. C<EXTEND>
will ensure that there is at least enough space on the stack for n further
items to be pushed.
If using the PUSH strategy, it is useful to understand in more detail how
pushing and the local stack pointer, C<SP> are implemented. The generated
C file will have access to (among others) the following macro definitions
or similar:
#define dSP SV **sp = PL_stack_sp
#define SP sp
#define PUSHs(s) *++sp = (s)
#define mPUSHi(i) sv_setiv(PUSHs(sv_newmortal()), (IV)(i))
#define PUTBACK PL_stack_sp = sp
#define SPAGAIN sp = PL_stack_sp
#define dXSARGS dSP; ....
The global (or per-interpreter) variable C<PL_stack_sp> is a pointer to
the current top-most entry on the stack, equal initially to
C<&ST(items-1)>. On entry to the XSUB, the C<dXSARGS> at its top will
cause the C<sp> variable to be declared and initialised. This becomes a
I<local> copy of the argument stack pointer. The standard stack
manipulation macros such as C<PUSHs> all use this local copy.
The XS parser will usually emit two lines of C code similar to these
around the PP code block lines:
SP -= items;
... PP lines ...
PUTBACK; return;
This has the effect of resetting the local copy of the stack pointer (but
I<not> the stack pointer itself) back to the base of the current stack
frame, discarding any passed arguments. The original arguments are still
on the stack. C<PUSHs()> etc will, starting at the base of the stack
frame, progressively overwrite any original arguments. Finally, the
C<PUTBACK> sets the real stack pointer to the copy, making the changes
permanent, and also allowing the caller to determine how many arguments
were returned.
Any functions called from the XSUB will only see the value of
C<PL_stack_sp> and not C<SP>. So when calling out to a function which
manipulates the stack, you may need to resynchronise the two; for example:
PUTBACK;
push_contents_of_array(av);
SPAGAIN;
The C<EXTEND(SP,n)> and C<mXPUSHfoo()> macros will update both
C<PL_stack_sp> and C<SP> if the extending causes the stack to be
reallocated.
Note that there are several C<mPUSHfoo()> macros, which generally create a
temporary SV, set its value to the argument, and push it onto the stack.
These are:
mPUSHs(sv) mortalise and push an SV
mPUSHi(iv) create+push mortal and set to the integer val
mPUSHu(uv) create+push mortal and set to the unsigned val
mPUSHn(n) create+push mortal and set to the num (float) val
mPUSHp(str, len) create+push mortal and set to the string+length
mPUSHpvs("string") create+push mortal and set to the literal string
(perl 5.38.0 onwards)
=head3 The NOT_IMPLEMENTED_YET: Keyword
void
foo(int a)
NOT_IMPLEMENTED_YET:
This keyword, as a fourth alternative to C<CODE>, C<PPCODE> and autocall,
generates a main body for the XSUB consisting solely of the C code:
Perl_croak(aTHX_ "Foo::Bar::foo: not implemented yet");
The current implementation is quite buggy in terms of parsing and where
the keyword can appear within an XSUB, so it's generally better to avoid
it. It is documented here for completeness.
=head2 The XSUB Output Part
Following an XSUB's code part, any results may be post-processed and
returned. Two keywords in particular support this: L<POSTCALL|/The
POSTCALL: Keyword>, which allows for a block of code to be added after
any autocall in order to post-process return values from the call, and
L<OUTPUT|/The OUTPUT: Keyword>, which tells the parser to generate code to
return the value of C<RETVAL> or to update the values of one or more
passed arguments.
These two optional keywords should each only be used once at most, and in
that order; but due to a parsing bug (kept for backwards compatibility),
they can appear in either order any number of times. But don't do that.
Note that the keywords described in L<XSUB Generic Keywords> and L<Sharing
XSUB bodies> may also appear in this part.
=head3 The POSTCALL: Keyword
The C<POSTCALL> keyword allows a block of code to be inserted directly after
any autocall or C<CODE> code block (although it's really only of use with
autocall). It's typically used for cleaning up the return value from the
autocall. For example these two XSUBs are equivalent:
int
foo(int a)
POSTCALL:
if (RETVAL < 0)
RETVAL = 0
int
foo(int a)
CODE:
RETVAL = foo(a);
if (RETVAL < 0)
RETVAL = 0
OUTPUT:
RETVAL
=head3 The OUTPUT: Keyword
# Common usage:
OUTPUT:
RETVAL
# Rare usage:
OUTPUT:
arg0
SETMAGIC: DISABLE
arg1
lib/perlxs.pod view on Meta::CPAN
aliasing, handled all four of the arithmetic operations, is now split into
four separate XSUBs, since C<ALIAS> and C<OVERLOAD> don't mix.
The main change to each arithmetic XSUB, apart from adding the C<OVERLOAD>
keyword, is that there is an extra C<swap> parameter. There's no real need
to use it for addition and multiplication, but it is important for the
non-commutative subtraction and division operations.
That example uses the C<T_PTROBJ> typemap to process the second argument,
which in the most general usage may not be an object. For example the
second and third of these lines will croak with an C<Expected foo to be of
type My::Num, got scalar> error:
$i13 + My::Num->new(7);
$i13 + 7;
$i13 + "7";
If it is necessary to handle this, then you may need to create your own
typemap: for example, something similar to C<T_PTROBJ>, but with an INPUT
template along the lines of:
T_MYNUM
SV *sv = $arg;
SvGETMAGIC(sv);
if (!SvROK(sv)) {
sv = sv_newmortal();
sv_setref_pv(sv, "$ntype", mynum_new(SvIV($arg));
}
....
Finally, although not directly related to XS, the following could be added
to F<Num.pm> to allow integer literals to be used directly:
sub import {
overload::constant integer =>
sub {
my $str = shift;
return My::Num->new($str);
};
}
which then allows these lines:
my $i2 = My::Num->new(2);
my $i7 = My::Num->new(7);
my $i13 = My::Num->new(13);
to be rewritten more cleanly as:
my $i2 = 2;
my $i7 = 7;
my $i13 = 13;
=head3 The ATTRS: Keyword
MODULE = Foo::Bar PACKAGE = Foo::Bar
SV*
debug()
ATTRS: lvalue
PPCODE:
# return $Foo::Bar::DEBUG, creating it if not already present
# (NB: XPUSHs() not needed here as the stack always has one
# allocated slot available when an XSUB is called):
PUSHs(GvSV(gv_fetchpvs("Foo::Bar::DEBUG", GV_ADD, SVt_IV)));
The C<ATTRS> keyword allows you to apply subroutine attributes to an XSUB
in a similar fashion to Perl subroutines. The XSUB in the example above is
equivalent to this Perl:
sub debug :lvalue { return $Foo::Bar::DEBUG }
and both can be called like this:
use Foo::Bar;
Foo::Bar::debug() = 99;
print "$Foo::Bar::DEBUG\n"; # prints 99
This keyword consumes all lines until the next keyword. The contents of
each line are interpreted as space-separated attributes. The attributes
are applied at the time the XS module is loaded. This:
void
foo(...)
ATTRS: aaa
bbb(x,y) ccc
is approximately equivalent to:
use attributes Foo::Bar, \&foo, 'aaa';
use attributes Foo::Bar, \&foo, 'bbb(x,y)';
use attributes Foo::Bar, \&foo, 'ccc';
User-defined attributes, just like with Perl subs, will trigger a call to
C<MODIFY_CODE_ATTRIBUTES()>, as described in L<attributes>.
Note that not all built-in subroutine attributes necessarily make sense
applied to XSUBs.
Currently the parsing of white-space is crude: C<bbb(x, y)> is
misinterpreted as two separate attributes, C<'bbb(x,'> and C<'y)'>.
The C<ATTRS> keyword can't currently be used in conjunction with C<ALIAS>
or C<INTERFACE>; in this case, the attributes are just silently ignored.
=head2 Sharing XSUB bodies
Sometimes you want to write several XSUBs which are very similar: they
all have the same signature, have the same generated code to convert
arguments and return values between Perl and C, and may only differ in a
few lines in the main body or in which C library function they wrap. It is
in fact possible to share the same XSUB function among multiple Perl CVs.
For example, C<&Foo::Bar::add> and C<&Foo::Bar::subtract> could be two
separate CVs in the Perl namespace which both point to the same XSUB,
C<XS_Foo__Bar__add()> say. But each CV holds some sort of unique
identifier which can be accessed by the XSUB so that it can determine
whether it should behave as C<add> or C<subtract>.
Both the C<ALIAS> and C<INTERFACE> keywords (described below) allow
multiple CVs to share the same XSUB. The difference between them is that
C<ALIAS> is intended for when you supply the main body of the XSUB
( run in 0.599 second using v1.01-cache-2.11-cpan-5511b514fd6 )