XS (Perl)

XS is a Perl foreign function interface through which a program can call a C or C++ subroutine. XS or xsub is an abbreviation of "eXternal Subroutine", where ''external'' refers to programming languages external to Perl.

XS also refers to a glue language for specifying calling interfaces supporting such interfaces (see below).

Background

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.

Perl interpreter

The Perl interpreter is a C program, so in principle there is no obstacle to calling from Perl to C. However, the XS interface is complex and highly technical, and using it requires some understanding of the interpreter. The earliest reference on the subject was th
perlguts
POD.

Wrappers

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

Example code

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 )

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 lik
ExtUtils::MakeMaker
can do this automatically. (To build manually: th
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 lik
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.

Difficulties

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.

See also

* 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.

References

* Jenness, Tim & Cozens, Simon (2002). "Extending and Embedding Perl". Greenwich: Manning Publications Co.

External links

perlxs
Perl XS application programming interface


Perl XS tutorial


Perl internal functions for those doing extensions


Perl API listing (autogenerated)


tutorial


building XS modules for C++

xs-fun
XS is fun: a simple and easy tutorial on writing Perl XS

{{Perl

Perl