=head2 Introduction
-XS is a language used to create an extension interface
-between Perl and some C library which one wishes to use with
-Perl. The XS interface is combined with the library to
-create a new library which can be linked to Perl. An B<XSUB>
-is a function in the XS language and is the core component
-of the Perl application interface.
-
-The XS compiler is called B<xsubpp>. This compiler will embed
-the constructs necessary to let an XSUB, which is really a C
-function in disguise, manipulate Perl values and creates the
-glue necessary to let Perl access the XSUB. The compiler
+XS is an interface description file format used to create an extension
+interface between Perl and C code (or a C library) which one wishes
+to use with Perl. The XS interface is combined with the library to
+create a new library which can then be either dynamically loaded
+or statically linked into perl. The XS interface description is
+written in the XS language and is the core component of the Perl
+extension interface.
+
+An B<XSUB> forms the basic unit of the XS interface. After compilation
+by the B<xsubpp> compiler, each XSUB amounts to a C function definition
+which will provide the glue between Perl calling conventions and C
+calling conventions.
+
+The glue code pulls the arguments from the Perl stack, converts these
+Perl values to the formats expected by a C function, call this C function,
+transfers the return values of the C function back to Perl.
+Return values here may be a conventional C return value or any C
+function arguments that may serve as output parameters. These return
+values may be passed back to Perl either by putting them on the
+Perl stack, or by modifying the arguments supplied from the Perl side.
+
+The above is a somewhat simplified view of what really happens. Since
+Perl allows more flexible calling conventions than C, XSUBs may do much
+more in practice, such as checking input parameters for validity,
+throwing exceptions (or returning undef/empty list) if the return value
+from the C function indicates failure, calling different C functions
+based on numbers and types of the arguments, providing an object-oriented
+interface, etc.
+
+Of course, one could write such glue code directly in C. However, this
+would be a tedious task, especially if one needs to write glue for
+multiple C functions, and/or one is not familiar enough with the Perl
+stack discipline and other such arcana. XS comes to the rescue here:
+instead of writing this glue C code in long-hand, one can write
+a more concise short-hand I<description> of what should be done by
+the glue, and let the XS compiler B<xsubpp> handle the rest.
+
+The XS language allows one to describe the mapping between how the C
+routine is used, and how the corresponding Perl routine is used. It
+also allows creation of Perl routines which are directly translated to
+C code and which are not related to a pre-existing C function. In cases
+when the C interface coincides with the Perl interface, the XSUB
+declaration is almost identical to a declaration of a C function (in K&R
+style). In such circumstances, there is another tool called C<h2xs>
+that is able to translate an entire C header file into a corresponding
+XS file that will provide glue to the functions/macros described in
+the header file.
+
+The XS compiler is called B<xsubpp>. This compiler creates
+the constructs necessary to let an XSUB manipulate Perl values, and
+creates the glue necessary to let Perl call the XSUB. The compiler
uses B<typemaps> to determine how to map C function parameters
-and variables to Perl values. The default typemap handles
-many common C types. A supplement typemap must be created
-to handle special structures and types for the library being
-linked.
+and output values to Perl values and back. The default typemap
+(which comes with Perl) handles many common C types. A supplementary
+typemap may also be needed to handle any special structures and types
+for the library being linked.
+
+A file in XS format starts with a C language section which goes until the
+first C<MODULE =Z<>> directive. Other XS directives and XSUB definitions
+may follow this line. The "language" used in this part of the file
+is usually referred to as the XS language.
See L<perlxstut> for a tutorial on the whole extension creation process.
-Note: For many extensions, Dave Beazley's SWIG system provides a
-significantly more convenient mechanism for creating the XS glue
+Note: For some extensions, Dave Beazley's SWIG system may provide a
+significantly more convenient mechanism for creating the extension glue
code. See L<http://www.cs.utah.edu/~beazley/SWIG> for more
information.
rpcb_gettime(host,timep)
char *host
time_t &timep
- OUTPUT:
+ OUTPUT:
timep
Any extension to Perl, including those containing XSUBs,
=head2 The Anatomy of an XSUB
+The simplest XSUBs consist of 3 parts: a description of the return
+value, the name of the XSUB routine and the names of its arguments,
+and a description of types or formats of the arguments.
+
The following XSUB allows a Perl program to access a C library function
called sin(). The XSUB will imitate the C function which takes a single
argument and returns a single value.
sin(x)
double x
-When using C pointers the indirection operator C<*> should be considered
-part of the type and the address operator C<&> should be considered part of
-the variable, as is demonstrated in the rpcb_gettime() function above. See
-the section on typemaps for more about handling qualifiers and unary
+When using parameters with C pointer types, as in
+
+ double string_to_double(char *s);
+
+there may be two ways to describe this argument to B<xsubpp>:
+
+ char * s
+ char &s
+
+Both these XS declarations correspond to the C<char*> C type, but they have
+different semantics. It is convenient to think that the indirection operator
+C<*> should be considered as a part of the type and the address operator C<&>
+should be considered part of the variable. See L<"The Typemap"> and
+L<"The & Unary Operator"> for more info about handling qualifiers and unary
operators in C types.
The function name and the return type must be placed on
-separate lines.
+separate lines and should be flush left-adjusted.
INCORRECT CORRECT
The function body may be indented or left-adjusted. The following example
shows a function with its body left-adjusted. Most examples in this
-document will indent the body.
+document will indent the body for better readability.
CORRECT
sin(x)
double x
+More complicated XSUBs may contain many other sections. Each section of
+an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:.
+However, the first two lines of an XSUB always contain the same data:
+descriptions of the return type and the names of the function and its
+parameters. Whatever immediately follows these is considered to be
+an INPUT: section unless explicitly marked with another keyword.
+(See L<The INPUT: Keyword>.)
+
+An XSUB section continues until another section-start keyword is found.
+
=head2 The Argument Stack
-The argument stack is used to store the values which are
+The Perl argument stack is used to store the values which are
sent as parameters to the XSUB and to store the XSUB's
-return value. In reality all Perl functions keep their
-values on this stack at the same time, each limited to its
-own range of positions on the stack. In this document the
+return value(s). In reality all Perl functions (including non-XSUB
+ones) keep their values on this stack all the same time, each limited
+to its own range of positions on the stack. In this document the
first position on that stack which belongs to the active
function will be referred to as position 0 for that function.
=head2 The RETVAL Variable
-The RETVAL variable is a magic variable which always matches
-the return type of the C library function. The B<xsubpp> compiler will
-supply this variable in each XSUB and by default will use it to hold the
-return value of the C library function being called. In simple cases the
-value of RETVAL will be placed in ST(0) of the argument stack where it can
-be received by Perl as the return value of the XSUB.
+The RETVAL variable is a special C variable that is declared automatically
+for you. The C type of RETVAL matches the return type of the C library
+function. The B<xsubpp> compiler will declare this variable in each XSUB
+with non-C<void> return type. By default the generated C function
+will use RETVAL to hold the return value of the C library function being
+called. In simple cases the value of RETVAL will be placed in ST(0) of
+the argument stack where it can be received by Perl as the return value
+of the XSUB.
If the XSUB has a return type of C<void> then the compiler will
-not supply a RETVAL variable for that function. When using
-the PPCODE: directive the RETVAL variable is not needed, unless used
-explicitly.
+not declare a RETVAL variable for that function. When using
+a PPCODE: section no manipulation of the RETVAL variable is required, the
+section may use direct stack manipulation to place output values on the stack.
If PPCODE: directive is not used, C<void> return value should be used
only for subroutines which do not return a value, I<even if> CODE:
The OUTPUT: keyword indicates that certain function parameters should be
updated (new values made visible to Perl) when the XSUB terminates or that
certain values should be returned to the calling Perl function. For
-simple functions, such as the sin() function above, the RETVAL variable is
-automatically designated as an output value. In more complex functions
+simple functions which have no CODE: or PPCODE: section,
+such as the sin() function above, the RETVAL variable is
+automatically designated as an output value. For more complex functions
the B<xsubpp> compiler will need help to determine which variables are output
variables.
rpcb_gettime(host,timep)
char *host
time_t &timep
- OUTPUT:
+ OUTPUT:
timep
The OUTPUT: keyword will also allow an output parameter to
rpcb_gettime(host,timep)
char *host
time_t &timep
- OUTPUT:
+ OUTPUT:
timep sv_setnv(ST(1), (double)timep);
B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
This keyword is used in more complicated XSUBs which require
special handling for the C function. The RETVAL variable is
-available but will not be returned unless it is specified
-under the OUTPUT: keyword.
+still declared, but it will not be returned unless it is specified
+in the OUTPUT: section.
The following XSUB is for a C function which requires special handling of
its parameters. The Perl usage is given first.
rpcb_gettime(host,timep)
char *host
time_t timep
- CODE:
+ CODE:
RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ OUTPUT:
timep
RETVAL
rpcb_gettime(host,timep)
char *host
time_t &timep
- INIT:
+ INIT:
printf("# Host is %s\n", host );
- OUTPUT:
+ OUTPUT:
timep
+Another use for the INIT: section is to check for preconditions before
+making a call to the C function:
+
+ long long
+ lldiv(a,b)
+ long long a
+ long long b
+ INIT:
+ if (a == 0 && b == 0)
+ XSRETURN_UNDEF;
+ if (b == 0)
+ croak("lldiv: cannot divide by 0");
+
=head2 The NO_INIT Keyword
The NO_INIT keyword is used to indicate that a function
rpcb_gettime(host,timep)
char *host
time_t &timep = NO_INIT
- OUTPUT:
+ OUTPUT:
timep
=head2 Initializing Function Parameters
-Function parameters are normally initialized with their
-values from the argument stack. The typemaps contain the
-code segments which are used to transfer the Perl values to
+C function parameters are normally initialized with their values from
+the argument stack (which in turn contains the parameters that were
+passed to the XSUB from Perl). The typemaps contain the
+code segments which are used to translate the Perl values to
the C parameters. The programmer, however, is allowed to
override the typemaps and supply alternate (or additional)
-initialization code.
+initialization code. Initialization code starts with the first
+C<=>, C<;> or C<+> on a line in the INPUT: section. The only
+exception happens if this C<;> terminates the line, then this C<;>
+is quietly ignored.
The following code demonstrates how to supply initialization code for
function parameters. The initialization code is eval'd within double
rpcb_gettime(host,timep)
char *host = (char *)SvPV($arg,PL_na);
time_t &timep = 0;
- OUTPUT:
+ OUTPUT:
timep
This should not be used to supply default values for parameters. One
another library function before it can be used. Default parameters are
covered in the next section.
-If the initialization begins with C<=>, then it is output on
-the same line where the input variable is declared. If the
-initialization begins with C<;> or C<+>, then it is output after
-all of the input variables have been declared. The C<=> and C<;>
-cases replace the initialization normally supplied from the typemap.
-For the C<+> case, the initialization from the typemap will precede
-the initialization code included after the C<+>. A global
+If the initialization begins with C<=>, then it is output in
+the declaration for the input variable, replacing the initialization
+supplied by the typemap. If the initialization
+begins with C<;> or C<+>, then it is performed after
+all of the input variables have been declared. In the C<;>
+case the initialization normally supplied by the typemap is not performed.
+For the C<+> case, the declaration for the variable will include the
+initialization from the typemap. A global
variable, C<%v>, is available for the truly rare case where
information from one initialization is needed in another
initialization.
+Here's a truly obscure example:
+
bool_t
rpcb_gettime(host,timep)
- time_t &timep ; /*\$v{time}=@{[$v{time}=$arg]}*/
- char *host + SvOK($v{time}) ? SvPV($arg,PL_na) : NULL;
- OUTPUT:
+ time_t &timep ; /* \$v{timep}=@{[$v{timep}=$arg]} */
+ char *host + SvOK($v{timep}) ? SvPV($arg,PL_na) : NULL;
+ OUTPUT:
timep
+The construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above
+example has a two-fold purpose: first, when this line is processed by
+B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated. Second,
+the text of the evaluated snippet is output into the generated C file
+(inside a C comment)! During the processing of C<char *host> line,
+$arg will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
+C<ST(1)>.
+
=head2 Default Parameter Values
-Default values can be specified for function parameters by
+Default values for XSUB arguments can be specified by
placing an assignment statement in the parameter list. The
default value may be a number or a string. Defaults should
always be used on the right-most parameters only.
To allow the XSUB for rpcb_gettime() to have a default host
value the parameters to the XSUB could be rearranged. The
XSUB will then call the real rpcb_gettime() function with
-the parameters in the correct order. Perl will call this
-XSUB with either of the following statements.
+the parameters in the correct order. This XSUB can be called
+from Perl with either of the following statements:
$status = rpcb_gettime( $timep, $host );
rpcb_gettime(timep,host="localhost")
char *host
time_t timep = NO_INIT
- CODE:
+ CODE:
RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ OUTPUT:
timep
RETVAL
=head2 The PREINIT: Keyword
-The PREINIT: keyword allows extra variables to be declared before the
-typemaps are expanded. If a variable is declared in a CODE: block then that
-variable will follow any typemap code. This may result in a C syntax
-error. To force the variable to be declared before the typemap code, place
-it into a PREINIT: block. The PREINIT: keyword may be used one or more
-times within an XSUB.
+The PREINIT: keyword allows extra variables to be declared immediately
+before or after the declartions of the parameters from the INPUT: section
+are emitted.
+
+If a variable is declared inside a CODE: section it will follow any typemap
+code that is emitted for the input parameters. This may result in the
+declaration ending up after C code, which is C syntax error. Similar
+errors may happen with an explicit C<;>-type or C<+>-type initialization of
+parameters is used (see L<"Initializing Function Parameters">). Declaring
+these variables in an INIT: section will not help.
+
+In such cases, to force an additional variable to be declared together
+with declarations of other variables, place the declaration into a
+PREINIT: section. The PREINIT: keyword may be used one or more times
+within an XSUB.
The following examples are equivalent, but if the code is using complex
typemaps then the first example is safer.
bool_t
rpcb_gettime(timep)
time_t timep = NO_INIT
- PREINIT:
+ PREINIT:
char *host = "localhost";
- CODE:
+ CODE:
RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ OUTPUT:
timep
RETVAL
-A correct, but error-prone example.
+For this particular case an INIT: keyword would generate the
+same C code as the PREINIT: keyword. Another correct, but error-prone example:
bool_t
rpcb_gettime(timep)
time_t timep = NO_INIT
- CODE:
+ CODE:
char *host = "localhost";
RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ OUTPUT:
+ timep
+ RETVAL
+
+Another way to declare C<host> is to use a C block in the CODE: section:
+
+ bool_t
+ rpcb_gettime(timep)
+ time_t timep = NO_INIT
+ CODE:
+ {
+ char *host = "localhost";
+ RETVAL = rpcb_gettime( host, &timep );
+ }
+ OUTPUT:
+ timep
+ RETVAL
+
+The ability to put additional declarations before the typemap entries are
+processed is very handy in the cases when typemap conversions manipulate
+some global state:
+
+ MyObject
+ mutate(o)
+ PREINIT:
+ MyState st = global_state;
+ INPUT:
+ MyObject o;
+ CLEANUP:
+ reset_to(global_state, st);
+
+Here we suppose that conversion to C<MyObject> in the INPUT: section and from
+MyObject when processing RETVAL will modify a global variable C<global_state>.
+After these conversions are performed, we restore the old value of
+C<global_state> (to avoid memory leaks, for example).
+
+There is another way to trade clarity for compactness: INPUT sections allow
+declaration of C variables which do not appear in the parameter list of
+a subroutine. Thus the above code for mutate() can be rewritten as
+
+ MyObject
+ mutate(o)
+ MyState st = global_state;
+ MyObject o;
+ CLEANUP:
+ reset_to(global_state, st);
+
+and the code for rpcb_gettime() can be rewritten as
+
+ bool_t
+ rpcb_gettime(timep)
+ time_t timep = NO_INIT
+ char *host = "localhost";
+ C_ARGS:
+ host, &timep
+ OUTPUT:
timep
RETVAL
enabled, the XSUB will invoke ENTER and LEAVE automatically.
To support potentially complex type mappings, if a typemap entry used
-by this XSUB contains a comment like C</*scope*/> then scoping will
-automatically be enabled for that XSUB.
+by an XSUB contains a comment like C</*scope*/> then scoping will
+be automatically enabled for that XSUB.
To enable scoping:
bool_t
rpcb_gettime(host,timep)
char *host
- PREINIT:
+ PREINIT:
time_t tt;
- INPUT:
+ INPUT:
time_t timep
- CODE:
+ CODE:
RETVAL = rpcb_gettime( host, &tt );
timep = tt;
- OUTPUT:
+ OUTPUT:
timep
RETVAL
bool_t
rpcb_gettime(host,timep)
- PREINIT:
+ PREINIT:
time_t tt;
- INPUT:
+ INPUT:
char *host
- PREINIT:
+ PREINIT:
char *h;
- INPUT:
+ INPUT:
time_t timep
- CODE:
+ CODE:
h = host;
RETVAL = rpcb_gettime( h, &tt );
timep = tt;
- OUTPUT:
+ OUTPUT:
+ timep
+ RETVAL
+
+Since INPUT sections allow declaration of C variables which do not appear
+in the parameter list of a subroutine, this may be shortened to:
+
+ bool_t
+ rpcb_gettime(host,timep)
+ time_t tt;
+ char *host;
+ char *h = host;
+ time_t timep;
+ CODE:
+ RETVAL = rpcb_gettime( h, &tt );
+ timep = tt;
+ OUTPUT:
timep
RETVAL
+(We used our knowledge that input conversion for C<char *> is a "simple" one,
+thus C<host> is initialized on the declaration line, and our assignment
+C<h = host> is not performed too early. Otherwise one would need to have the
+assignment C<h = host> in a CODE: or INIT: section.)
+
=head2 Variable-length Parameter Lists
XSUBs can have variable-length parameter lists by specifying an ellipsis
bool_t
rpcb_gettime(timep, ...)
time_t timep = NO_INIT
- PREINIT:
+ PREINIT:
char *host = "localhost";
STRLEN n_a;
- CODE:
- if( items > 1 )
- host = (char *)SvPV(ST(1), n_a);
- RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ CODE:
+ if( items > 1 )
+ host = (char *)SvPV(ST(1), n_a);
+ RETVAL = rpcb_gettime( host, &timep );
+ OUTPUT:
timep
RETVAL
The C_ARGS: keyword allows creating of XSUBS which have different
calling sequence from Perl than from C, without a need to write
-CODE: or CPPCODE: section. The contents of the C_ARGS: paragraph is
+CODE: or PPCODE: section. The contents of the C_ARGS: paragraph is
put as the argument to the called C function without any change.
-For example, suppose that C function is declared as
+For example, suppose that a C function is declared as
symbolic nth_derivative(int n, symbolic function, int flags);
nth_derivative(function, n)
symbolic function
int n
- C_ARGS:
+ C_ARGS:
n, function, default_flags
=head2 The PPCODE: Keyword
control the argument stack for the XSUBs return values. Occasionally one
will want an XSUB to return a list of values rather than a single value.
In these cases one must use PPCODE: and then explicitly push the list of
-values on the stack. The PPCODE: and CODE: keywords are not used
+values on the stack. The PPCODE: and CODE: keywords should not be used
together within the same XSUB.
+The actual difference between PPCODE: and CODE: sections is in the
+initialization of C<SP> macro (which stands for the I<current> Perl
+stack pointer), and in the handling of data on the stack when returning
+from an XSUB. In CODE: sections SP preserves the value which was on
+entry to the XSUB: SP is on the function pointer (which follows the
+last parameter). In PPCODE: sections SP is moved backward to the
+beginning of the parameter list, which allows C<PUSH*()> macros
+to place output values in the place Perl expects them to be when
+the XSUB returns back to Perl.
+
+The generated trailer for a CODE: section ensures that the number of return
+values Perl will see is either 0 or 1 (depending on the C<void>ness of the
+return value of the C function, and heuristics mentioned in
+L<"The RETVAL Variable">). The trailer generated for a PPCODE: section
+is based on the number of return values and on the number of times
+C<SP> was updated by C<[X]PUSH*()> macros.
+
+Note that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally
+well in CODE: sections and PPCODE: sections.
+
The following XSUB will call the C rpcb_gettime() function
and will return its two output values, timep and status, to
Perl as a single list.
void
rpcb_gettime(host)
char *host
- PREINIT:
+ PREINIT:
time_t timep;
bool_t status;
- PPCODE:
+ PPCODE:
status = rpcb_gettime( host, &timep );
EXTEND(SP, 2);
PUSHs(sv_2mortal(newSViv(status)));
SV *
rpcb_gettime(host)
char * host
- PREINIT:
+ PREINIT:
time_t timep;
bool_t x;
- CODE:
+ CODE:
ST(0) = sv_newmortal();
if( rpcb_gettime( host, &timep ) )
sv_setnv( ST(0), (double)timep);
SV *
rpcb_gettime(host)
char * host
- PREINIT:
+ PREINIT:
time_t timep;
bool_t x;
- CODE:
+ CODE:
ST(0) = sv_newmortal();
if( rpcb_gettime( host, &timep ) ){
sv_setnv( ST(0), (double)timep);
void
rpcb_gettime(host)
char *host
- PREINIT:
+ PREINIT:
time_t timep;
- PPCODE:
+ PPCODE:
if( rpcb_gettime( host, &timep ) )
PUSHs(sv_2mortal(newSViv(timep)));
else{
- /* Nothing pushed on stack, so an empty */
- /* list is implicitly returned. */
+ /* Nothing pushed on stack, so an empty
+ * list is implicitly returned. */
}
Some people may be inclined to include an explicit C<return> in the above
the XSUB stack is properly adjusted. Consult L<perlguts/"API LISTING"> for
other C<XSRETURN> macros.
+Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
+rewrite this example as:
+
+ int
+ rpcb_gettime(host)
+ char *host
+ PREINIT:
+ time_t timep;
+ CODE:
+ RETVAL = rpcb_gettime( host, &timep );
+ if (RETVAL == 0)
+ XSRETURN_UNDEF;
+ OUTPUT:
+ RETVAL
+
+In fact, one can put this check into a CLEANUP: section as well. Together
+with PREINIT: simplifications, this leads to:
+
+ int
+ rpcb_gettime(host)
+ char *host
+ time_t timep;
+ CLEANUP:
+ if (RETVAL == 0)
+ XSRETURN_UNDEF;
+
=head2 The REQUIRE: Keyword
The REQUIRE: keyword is used to indicate the minimum version of the
bool_t
rpcb_gettime(timep, ...)
time_t timep = NO_INIT
- PROTOTYPE: $;$
- PREINIT:
+ PROTOTYPE: $;$
+ PREINIT:
char *host = "localhost";
STRLEN n_a;
- CODE:
+ CODE:
if( items > 1 )
host = (char *)SvPV(ST(1), n_a);
RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ OUTPUT:
timep
RETVAL
rpcb_gettime(host,timep)
char *host
time_t &timep
- ALIAS:
+ ALIAS:
FOO::gettime = 1
BAR::getit = 2
- INIT:
+ INIT:
printf("# ix = %d\n", ix );
- OUTPUT:
+ OUTPUT:
timep
=head2 The INTERFACE: Keyword
This keyword declares the current XSUB as a keeper of the given
calling signature. If some text follows this keyword, it is
considered as a list of functions which have this signature, and
-should be attached to XSUBs.
+should be attached to the current XSUB.
-Say, if you have 4 functions multiply(), divide(), add(), subtract() all
-having the signature
+For example, if you have 4 C functions multiply(), divide(), add(),
+subtract() all having the signature:
symbolic f(symbolic, symbolic);
-you code them all by using XSUB
+you can make them all to use the same XSUB using this:
symbolic
interface_s_ss(arg1, arg2)
multiply divide
add subtract
-The advantage of this approach comparing to ALIAS: keyword is that one
+(This is the complete XSUB code for 4 Perl functions!) Four generated
+Perl function share names with corresponding C functions.
+
+The advantage of this approach comparing to ALIAS: keyword is that there
+is no need to code a switch statement, each Perl function (which shares
+the same XSUB) knows which C function it should call. Additionally, one
can attach an extra function remainder() at runtime by using
-
+
CV *mycv = newXSproto("Symbolic::remainder",
XS_Symbolic_interface_s_ss, __FILE__, "$$");
XSINTERFACE_FUNC_SET(mycv, remainder);
-(This example supposes that there was no INTERFACE_MACRO: section,
-otherwise one needs to use something else instead of
-C<XSINTERFACE_FUNC_SET>.)
+say, from another XSUB. (This example supposes that there was no
+INTERFACE_MACRO: section, otherwise one needs to use something else instead of
+C<XSINTERFACE_FUNC_SET>, see the next section.)
=head2 The INTERFACE_MACRO: Keyword
interface_s_ss(arg1, arg2)
symbolic arg1
symbolic arg2
- INTERFACE_MACRO:
+ INTERFACE_MACRO:
XSINTERFACE_FUNC_BYOFFSET
XSINTERFACE_FUNC_BYOFFSET_set
- INTERFACE:
+ INTERFACE:
multiply divide
add subtract
rpcb_gettime(host,timep)
char *host
time_t &timep
- OUTPUT:
+ OUTPUT:
timep
The XS module can use INCLUDE: to pull that file into it.
long
rpcb_gettime(a,b)
CASE: ix == 1
- ALIAS:
+ ALIAS:
x_gettime = 1
- INPUT:
+ INPUT:
# 'a' is timep, 'b' is host
char *b
time_t a = NO_INIT
- CODE:
+ CODE:
RETVAL = rpcb_gettime( b, &a );
- OUTPUT:
+ OUTPUT:
a
RETVAL
CASE:
# 'a' is host, 'b' is timep
char *a
time_t &b = NO_INIT
- OUTPUT:
+ OUTPUT:
b
RETVAL
=head2 The & Unary Operator
-The & unary operator is used to tell the compiler that it should dereference
-the object when it calls the C function. This is used when a CODE: block is
-not used and the object is a not a pointer type (the object is an C<int> or
-C<long> but not a C<int*> or C<long*>).
+The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
+that it should convert a Perl value to/from C using the C type to the left
+of C<&>, but provide a pointer to this value when the C function is called.
+
+This is useful to avoid a CODE: block for a C function which takes a parameter
+by reference. Typically, the parameter should be not a pointer type (an
+C<int> or C<long> but not a C<int*> or C<long*>).
-The following XSUB will generate incorrect C code. The xsubpp compiler will
+The following XSUB will generate incorrect C code. The B<xsubpp> compiler will
turn this into code which calls C<rpcb_gettime()> with parameters C<(char
*host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
parameter to be of type C<time_t*> rather than C<time_t>.
rpcb_gettime(host,timep)
char *host
time_t timep
- OUTPUT:
+ OUTPUT:
timep
-That problem is corrected by using the C<&> operator. The xsubpp compiler
+That problem is corrected by using the C<&> operator. The B<xsubpp> compiler
will now turn this into code which calls C<rpcb_gettime()> correctly with
parameters C<(char *host, time_t *timep)>. It does this by carrying the
C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
rpcb_gettime(host,timep)
char *host
time_t &timep
- OUTPUT:
+ OUTPUT:
timep
=head2 Inserting Comments and C Preprocessor Directives
#if ... version2
#endif
-because otherwise xsubpp will believe that you made a duplicate
+because otherwise B<xsubpp> will believe that you made a duplicate
definition of the function. Also, put a blank line before the
#else/#endif so it will not be seen as part of the function body.
=head2 Using XS With C++
-If a function is defined as a C++ method then it will assume
+If an XSUB name contains C<::>, it is considered to be a C++ method.
+The generated Perl function will assume that
its first argument is an object pointer. The object pointer
will be stored in a variable called THIS. The object should
have been created by C++ with the new() function and should
blessing of the object by Perl can be handled by a typemap. An example
typemap is shown at the end of this section.
-If the method is defined as static it will call the C++
+If the return type of the XSUB includes C<static>, the method is considered
+to be a static method. It will call the C++
function using the class::method() syntax. If the method is not static
the function will be called using the THIS-E<gt>method() syntax.
color::set_blue( val )
int val
-Both functions will expect an object as the first parameter. The xsubpp
-compiler will call that object C<THIS> and will use it to call the specified
-method. So in the C++ code the blue() and set_blue() methods will be called
-in the following manner.
+Both Perl functions will expect an object as the first parameter. In the
+generated C++ code the object is called C<THIS>, and the method call will
+be performed on this object. So in the C++ code the blue() and set_blue()
+methods will be called as this:
RETVAL = THIS->blue();
THIS->set_blue( val );
If the function's name is B<DESTROY> then the C++ C<delete> function will be
-called and C<THIS> will be given as its parameter.
+called and C<THIS> will be given as its parameter. The generated C++ code for
void
color::DESTROY()
-The C++ code will call C<delete>.
+will look like this:
+
+ color *THIS = ...; // Initialized as in typemap
delete THIS;
color *
color::new()
-The C++ code will call C<new>.
+The generated C++ code will call C<new>.
- RETVAL = new color();
+ RETVAL = new color();
The following is an example of a typemap that could be used for this C++
example.
=head2 Interface Strategy
When designing an interface between Perl and a C library a straight
-translation from C to XS is often sufficient. The interface will often be
+translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
+However, sometimes the interface will look
very C-like and occasionally nonintuitive, especially when the C function
-modifies one of its parameters. In cases where the programmer wishes to
+modifies one of its parameters, or returns failure inband (as in "negative
+return values mean failure"). In cases where the programmer wishes to
create a more Perl-like interface the following strategy may help to
identify the more critical parts of the interface.
-Identify the C functions which modify their parameters. The XSUBs for
-these functions may be able to return lists to Perl, or may be
-candidates to return undef or an empty list in case of failure.
+Identify the C functions with input/output or output parameters. The XSUBs for
+these functions may be able to return lists to Perl.
+
+Identify the C functions which use some inband info as an indication
+of failure. They may be
+candidates to return undef or an empty list in case of failure. If the
+failure may be detected without a call to the C function, you may want to use
+an INIT: section to report the failure. For failures detectable after the C
+function returns one may want to use a CLEANUP: section to process the
+failure. In more complicated cases use CODE: or PPCODE: sections.
+
+If many functions use the same failure indication based on the return value,
+you may want to create a special typedef to handle this situation. Put
+
+ typedef int negative_is_failure;
+
+near the beginning of XS file, and create an OUTPUT typemap entry
+for C<negative_is_failure> which converts negative values to C<undef>, or
+maybe croak()s. After this the return value of type C<negative_is_failure>
+will create more Perl-like interface.
Identify which values are used by only the C and XSUB functions
-themselves. If Perl does not need to access the contents of the value
+themselves, say, when a parameter to a function should be a contents of a
+global variable. If Perl does not need to access the contents of the value
then it may not be necessary to provide a translation for that value
from C to Perl.
Identify the pointers in the C function parameter lists and return
-values. Some pointers can be handled in XS with the & unary operator on
-the variable name while others will require the use of the * operator on
-the type name. In general it is easier to work with the & operator.
+values. Some pointers may be used to implement input/output or
+output parameters, they can be handled in XS with the C<&> unary operator,
+and, possibly, using the NO_INIT keyword.
+Some others will require handling of types like C<int *>, and one needs
+to decide what a useful Perl translation will do in such a case. When
+the semantic is clear, it is advisable to put the translation into a typemap
+file.
Identify the structures used by the C functions. In many
cases it may be helpful to use the T_PTROBJ typemap for
these structures so they can be manipulated by Perl as
-blessed objects.
+blessed objects. (This is handled automatically by C<h2xs -x>.)
+
+If the same C type is used in several different contexts which require
+different translations, C<typedef> several new types mapped to this C type,
+and create separate F<typemap> entries for these new types. Use these
+types in declarations of return type and parameters to XSUBs.
=head2 Perl Objects And C Structures
void
rpcb_DESTROY(netconf)
Netconfig *netconf
- CODE:
+ CODE:
printf("Now in NetconfigPtr::DESTROY\n");
free( netconf );
The typemap is a collection of code fragments which are used by the B<xsubpp>
compiler to map C function parameters and values to Perl values. The
typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
-C<OUTPUT>. Any unlabelled initial section is assumed to be a C<TYPEMAP>
-section if a name is not explicitly specified. The INPUT section tells
+C<OUTPUT>. An unlabelled initial section is assumed to be a C<TYPEMAP>
+section. The INPUT section tells
the compiler how to translate Perl values
into variables of certain C types. The OUTPUT section tells the compiler
how to translate the values from certain C types into values Perl can
here. Note that the C type is separated from the XS type with a tab and
that the C unary operator C<*> is considered to be a part of the C type name.
- TYPEMAP
- Netconfig *<tab>T_PTROBJ
+ TYPEMAP
+ Netconfig *<tab>T_PTROBJ
Here's a more complicated example: suppose that you wanted C<struct
netconfig> to be blessed into the class C<Net::Config>. One way to do
SV *
rpcb_gettime(host="localhost")
char *host
- PREINIT:
+ PREINIT:
time_t timep;
- CODE:
+ CODE:
ST(0) = sv_newmortal();
if( rpcb_gettime( host, &timep ) )
sv_setnv( ST(0), (double)timep );
void
rpcb_DESTROY(netconf)
Netconfig *netconf
- CODE:
+ CODE:
printf("NetconfigPtr::DESTROY\n");
free( netconf );
=head1 AUTHOR
-Dean Roehrich <F<roehrich@cray.com>>
-Jul 8, 1996
+Originally written by Dean Roehrich <F<roehrich@cray.com>>.
+
+Maintained since 1996 by The Perl Porters <F<perlbug@perl.com>>.
=head2 Version caveat
-This tutorial tries hard to keep up with the latest development versions
-of Perl. This often means that it is sometimes in advance of the latest
-released version of Perl, and that certain features described here might
-not work on earlier versions. See the section on "Troubleshooting
-these Examples" for more information.
+When writing a Perl extension for general consumption, one should expect that
+the extension will be used with versions of Perl different from the
+version available on your machine. Since you are reading this document,
+the version of Perl on your machine is probably 5.005 or later, but the users
+of your extension may have more ancient versions.
+
+To understand what kinds of incompatibilities one may expect, and in the rare
+case that the version of Perl on your machine is older than this document,
+see the section on "Troubleshooting these Examples" for more information.
+
+If your extension uses some features of Perl which are not available on older
+releases of Perl, your users would appreciate an early meaningful warning.
+You would probably put this information into the F<README> file, but nowadays
+installation of extensions may be performed automatically, guided by F<CPAN.pm>
+module or other tools.
+
+In MakeMaker-based installations, F<Makefile.PL> provides the earliest
+opportunity to perform version checks. One can put something like this
+in F<Makefile.PL> for this purpose:
+
+ eval { require 5.007 }
+ or die <<EOD;
+ ############
+ ### This module uses frobnication framework which is not available before
+ ### version 5.007 of Perl. Upgrade your Perl before installing Kara::Mba.
+ ############
+ EOD
=head2 Dynamic Loading versus Static Loading
=head2 The XSUBPP Program
-The xsubpp program takes the XS code in the .xs file and translates it into
+The B<xsubpp> program takes the XS code in the .xs file and translates it into
C code, placing it in a file whose suffix is .c. The C code created makes
heavy use of the C functions within Perl.
=head2 The TYPEMAP file
-The xsubpp program uses rules to convert from Perl's data types (scalar,
+The B<xsubpp> program uses rules to convert from Perl's data types (scalar,
array, etc.) to C's data types (int, char, etc.). These rules are stored
in the typemap file ($PERLLIB/ExtUtils/typemap). This file is split into
three parts.
The first section maps various C data types to a name, which corresponds
somewhat with the various Perl types. The second section contains C code
-which xsubpp uses to handle input parameters. The third section contains
-C code which xsubpp uses to handle output parameters.
+which B<xsubpp> uses to handle input parameters. The third section contains
+C code which B<xsubpp> uses to handle output parameters.
Let's take a look at a portion of the .c file created for our extension.
The file name is Mytest.c:
=back
-=head2 More about XSUBPP
+=head2 Anatomy of .xs file
+
+The .xs file of L<"EXAMPLE 4"> contained some new elements. To understand
+the meaning of these elements, pay attention to the line which reads
+
+ MODULE = Mytest2 PACKAGE = Mytest2
+
+Anything before this line is plain C code which describes which headers
+to include, and defines some convenience functions. No translations are
+performed on this part, it goes into the generated output C file as is.
+
+Anything after this line is the description of XSUB functions.
+These descriptions are translated by B<xsubpp> into C code which
+implements these functions using Perl calling conventions, and which
+makes these functions visible from Perl interpreter.
+
+Pay a special attention to the function C<constant>. This name appears
+twice in the generated .xs file: once in the first part, as a static C
+function, the another time in the second part, when an XSUB interface to
+this static C function is defined.
+
+This is quite typical for .xs files: usually the .xs file provides
+an interface to an existing C function. Then this C function is defined
+somewhere (either in an external library, or in the first part of .xs file),
+and a Perl interface to this function (i.e. "Perl glue") is described in the
+second part of .xs file. The situation in L<"EXAMPLE 1">, L<"EXAMPLE 2">,
+and L<"EXAMPLE 3">, when all the work is done inside the "Perl glue", is
+somewhat of an exception rather than the rule.
+
+=head2 Getting the fat out of XSUBs
+
+In L<"EXAMPLE 4"> the second part of .xs file contained the following
+description of an XSUB:
+
+ double
+ foo(a,b,c)
+ int a
+ long b
+ const char * c
+ OUTPUT:
+ RETVAL
+
+Note that in contrast with L<"EXAMPLE 1">, L<"EXAMPLE 2"> and L<"EXAMPLE 3">,
+this description does not contain the actual I<code> for what is done
+is done during a call to Perl function foo(). To understand what is going
+on here, one can add a CODE section to this XSUB:
+
+ double
+ foo(a,b,c)
+ int a
+ long b
+ const char * c
+ CODE:
+ RETVAL = foo(a,b,c);
+ OUTPUT:
+ RETVAL
+
+However, these two XSUBs provide almost identical generated C code: B<xsubpp>
+compiler is smart enough to figure out the C<CODE:> section from the first
+two lines of the description of XSUB. What about C<OUTPUT:> section? In
+fact, that is absolutely the same! The C<OUTPUT:> section can be removed
+as well, I<as far as C<CODE:> section or C<PPCODE:> section> is not
+specified: B<xsubpp> can see that it needs to generate a function call
+section, and will autogenerate the OUTPUT section too. Thus one can
+shortcut the XSUB to become:
+
+ double
+ foo(a,b,c)
+ int a
+ long b
+ const char * c
+
+Can we do the same with an XSUB
+
+ int
+ is_even(input)
+ int input
+ CODE:
+ RETVAL = (input % 2 == 0);
+ OUTPUT:
+ RETVAL
+
+of L<"EXAMPLE 2">? To do this, one needs to define a C function C<int
+is_even(int input)>. As we saw in L<Anatomy of .xs file>, a proper place
+for this definition is in the first part of .xs file. In fact a C function
+
+ int
+ is_even(int arg)
+ {
+ return (arg % 2 == 0);
+ }
+
+is probably overkill for this. Something as simple as a C<#define> will
+do too:
+
+ #define is_even(arg) ((arg) % 2 == 0)
+
+After having this in the first part of .xs file, the "Perl glue" part becomes
+as simple as
+
+ int
+ is_even(input)
+ int input
+
+This technique of separation of the glue part from the workhorse part has
+obvious tradeoffs: if you want to change a Perl interface, you need to
+change two places in your code. However, it removes a lot of clutter,
+and makes the workhorse part independent from idiosyncrasies of Perl calling
+convention. (In fact, there is nothing Perl-specific in the above description,
+a different version of B<xsubpp> might have translated this to TCL glue or
+Python glue as well.)
+
+=head2 More about XSUB arguments
With the completion of Example 4, we now have an easy way to simulate some
real-life libraries whose interfaces may not be the cleanest in the world.
We shall now continue with a discussion of the arguments passed to the
-xsubpp compiler.
+B<xsubpp> compiler.
When you specify arguments to routines in the .xs file, you are really
passing three pieces of information for each argument listed. The first
piece is the order of that argument relative to the others (first, second,
etc). The second is the type of argument, and consists of the type
declaration of the argument (e.g., int, char*, etc). The third piece is
-the exact way in which the argument should be used in the call to the
-library function from this XSUB. This would mean whether or not to place
-a "&" before the argument or not, meaning the argument expects to be
-passed the address of the specified data type.
+the calling convention for the argument in the call to the library function.
+
+While Perl passes arguments to functions by reference,
+C passes arguments by value; to implement a C function which modifies data
+of one of the "arguments", the actual argument of this C function would be
+a pointer to the data. Thus two C functions with declarations
+
+ int string_length(char *s);
+ int upper_case_char(char *cp);
+
+may have completely different semantics: the first one may inspect an array
+of chars pointed by s, and the second one may immediately dereference C<cp>
+and manipulate C<*cp> only (using the return value as, say, a success
+indicator). From Perl one would use these functions in
+a completely different manner.
+
+One conveys this info to B<xsubpp> by replacing C<*> before the
+argument by C<&>. C<&> means that the argument should be passed to a library
+function by its address. The above two function may be XSUB-ified as
+
+ int
+ string_length(s)
+ char * s
+
+ int
+ upper_case_char(cp)
+ char &cp
-There is a difference between the two arguments in this hypothetical function:
+For example, consider:
int
foo(a,b)
char &a
char * b
-The first argument to this function would be treated as a char and assigned
+The first Perl argument to this function would be treated as a char and assigned
to the variable a, and its address would be passed into the function foo.
-The second argument would be treated as a string pointer and assigned to the
+The second Perl argument would be treated as a string pointer and assigned to the
variable b. The I<value> of b would be passed into the function foo. The
-actual call to the function foo that xsubpp generates would look like this:
+actual call to the function foo that B<xsubpp> generates would look like this:
foo(&a, b);
-Xsubpp will parse the following function argument lists identically:
+B<xsubpp> will parse the following function argument lists identically:
char &a
char&a
therefore the first argument passed to the XSUB, ST(1) is the second
argument, and so on.
-When you list the arguments to the XSUB in the .xs file, that tells xsubpp
+When you list the arguments to the XSUB in the .xs file, that tells B<xsubpp>
which argument corresponds to which of the argument stack (i.e., the first
one listed is the first argument, and so on). You invite disaster if you
do not list them in the same order as the function expects them.
The arg variable is initially set by taking the value from ST(0), then is
stored back into ST(0) at the end of the routine.
+XSUBs are also allowed to return lists, not just scalars. This must be
+done by manipulating stack values ST(0), ST(1), etc, in a subtly
+different way. See L<perlxs> for details.
+
+XSUBs are also allowed to avoid automatic conversion of Perl function arguments
+to C function arguments. See L<perlxs> for details. Some people prefer
+manual conversion by inspecting C<ST(i)> even in the cases when automatic
+conversion will do, arguing that this makes the logic of an XSUB call clearer.
+Compare with L<"Getting the fat out of XSUBs"> for a similar tradeoff of
+a complete separation of "Perl glue" and "workhorse" parts of an XSUB.
+
+While experts may argue about these idioms, a novice to Perl guts may
+prefer a way which is as little Perl-guts-specific as possible, meaning
+automatic conversion and automatic call generation, as in
+L<"Getting the fat out of XSUBs">. This approach has the additional
+benefit of protecting the XSUB writer from future changes to the Perl API.
+
=head2 Extending your Extension
Sometimes you might want to provide some extra methods or subroutines
void
statfs(path)
char * path
- PREINIT:
+ INIT:
int i;
struct statfs buf;
=item *
-The PREINIT: directive contains code that will be placed immediately after
-variable declaration and before the argument stack is decoded. Some compilers
-cannot handle variable declarations at arbitrary locations inside a function,
+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 *
returned.
We do this by using the PPCODE: directive, rather than the CODE: directive.
-This tells xsubpp that we will be managing the return values that will be
+This tells B<xsubpp> that we will be managing the return values that will be
put on the argument stack by ourselves.
=item *
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.
+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
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, 9);
+
+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 (Coming Soon)
=head2 Last Changed
-1999/5/25
+1999/11/30
projects / p5sagit/p5-mst-13.2.git / commitdiff