XS (Perl)

Subroutine libraries in Perl are called modules, and modules that contain xsubs are called XS modules. Perl provides a framework for developing, packaging, distributing, and installing modules.

It may be desirable for a Perl program to invoke a C subroutine in order to handle very CPU or memory intensive tasks, to interface with hardware or low-level system facilities, or to make use of existing C subroutine libraries.

It is possible to write XS modules that wrap C++ code. Doing so is mostly a matter of configuring the module build system.[1]

The following shows an XS module that exposes a function concat() to concatenate two strings (i.e., the equivalent of Perl’s . operator).

#define PERL_NO_GET_CONTEXT
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"

SV* _do_sv_catsv (pTHX_ SV* one_sv, SV* two_sv ) {
    SV* one_copy = newSVsv(one_sv);
    sv_catsv(one_copy, two_sv);
    return one_copy;
}

MODULE = Demo::XSModule      PACKAGE = Demo::XSModule

SV*
concat (SV* one_sv, SV* two_sv)
    CODE:
        SV* to_return = _do_sv_catsv( aTHX_ one_sv, two_sv );
        RETVAL = to_return;

    OUTPUT:
        RETVAL

The first four lines (#define and #include statements) are standard boilerplate.

After then follow any number of plain C functions that are callable locally.

The section that starts with MODULE = Demo::XSModule defines the Perl interface to this code using the actual XS macro language. Note that the C code under the CODE: section calls the _do_sv_catsv() pure-C function that was defined in the prior section.

Perl’s documentation explains the meaning and purpose of all of the “special” symbols (e.g., aTHX_ and RETVAL) shown above.

To make this module available to Perl it must be compiled. Build tools like ExtUtils::MakeMaker can do this automatically. (To build manually: the xsubpp tool parses an XS module and outputs C source code; that source code is then compiled to a shared library and placed in a directory where Perl can find it.) Perl code then uses a module like XSLoader to load the compiled XS module. At this point Perl can call Demo::XSModule::concat('foo', 'bar') and receive back a string foobar, as if concat() were itself written in Perl.

Note that, for building Perl interfaces to preexisting C libraries, the h2xs can automate much of the creation of the XS file itself.

Creation and maintenance of XS modules requires expertise with C itself as well as Perl’s extensive C API. XS modules may only be installed if a C compiler and the header files that the Perl interpreter was compiled against are available. Also, new versions of Perl may break binary compatibility requiring XS modules to be recompiled.

• SWIG, an alternative to XS which also supports calling C and C++ functions from several other languages.
• FFI, a mechanism which enables calling routines written in another language.

• Jenness, Tim & Cozens, Simon (2002). "Extending and Embedding Perl". Greenwich: Manning Publications Co. ISBN 1-930110-82-0

• perlxs Perl XS application programming interface
• perlxstut Perl XS tutorial
• perlguts Perl internal functions for those doing extensions
• perlapi Perl API listing (autogenerated)
• XS Mechanics tutorial
• Perl and C++ building XS modules for C++
• xs-fun XS is fun: a simple and easy tutorial on writing Perl XS