18.4.1 What Does xsubpp Do?

It pays to understand a little bit about the glue code generated by xsubpp. When xsubpp is given the XS snippet shown above, it creates a function called Fractal_xs_draw_mandel (in Fractal.c) with the same signature as the XS declaration. This function translates the arguments supplied in Perl space to the C function's parameters, calls the real draw_mandel function, and finally packages its return value into a Perl value.

XS provides several keywords to either inject your own code at suitable locations inside the generated function or completely replace the generated glue code with your own. For example, you can write typemap functions that handle how Perl arguments get translated to C; you can use the CODE keyword (described later) to specify that you are supplying your own code.

With this brief overview in mind, let us now look at a few of the important aspects of the XS language.

18.4.2 Default and Optional Parameters

Parameters can have default values but, as in C++, can be applied only to the rightmost parameters:

draw_mandel (file,width,height,orig_real,orig_imag,range,depth=30)

This allows you to optionally skip the last parameter when calling from Perl.

18.4.3 Modifying Parameters

XS allows you to modify parameters before they are given to the real draw_mandel function:

int 
draw_mandel (filename,width,height,origin_real,origin_imag,range,depth)
      char*  filename
      int    width
      int    height
      double origin_real
      double origin_imag
      double range
      double depth
    INIT:
    if (width > 400) { 
        fprintf (stderr, "Width cannot exceed 400. Truncating.\n";
        width = 400;
    }

The INIT: keyword tells XS to insert the code following it between the argument translation (from Perl to C) and the call to the real function.

In SWIG, you would use a named typemap for the same effect. The XS approach, however, allows you to make a decision based on more than one parameter. For example, if you had to maintain a certain aspect ratio, you would have to look at both width and height and modify one of them. A typemap cannot give you this flexibility because it looks at each parameter in isolation.

Incidentally, the PREINIT: keyword can be used to insert variable declarations; xsubpp puts these declarations ahead of any generated code. Of course, this keyword is not important if you compile the glue code with a C++ compiler, since it allows you to declare variables anywhere in the code.

18.4.4 Special Code

You can write the glue code yourself if you want. Consider the sin() function in the math library, which requires you to supply the angle in radians. You can create a new function in Perl to accept the angle in degrees using the CODE keyword, like this (the indentation scheme is arbitrary):

double
d_sin(angle)
   double angle
  CODE:
   RETVAL = sin(angle  * PI / 180);
  OUTPUT: 
   RETVAL

When xsubpp sees the CODE keyword, it just maps the arguments from Perl data types to C types and leaves you to supply the rest of the code, which means that you have to make the call to the underlying external subroutine yourself. The CODE directive does not change the essential structure of the C call; you can modify input parameters and you can return at most one result value.

The OUTPUT: directive tells xsubpp to supply some code to package the returned result and load it back into Perl space. RETVAL is automatically declared by xsubpp to match the return value of the function. In the preceding example, the return value of sin() is the only output parameter and is listed under OUTPUT.

The CODE directive does not help if you want a variable number of input parameters or returned results. In this case, you use the PPCODE directive and explicitly manage the entire argument stack. We will have more on this in Chapter 20.

Please take a look at the XS documentation for other keywords, details, and examples.

18.4.5 C++ Code

XS supports two special procedures for automatically creating and deleting C++ objects. Consider the following XS code for a module called Car:

Car*
Car::new()

void
Car::DESTROY()

void
Car::turn_left()

When you say new Car in Perl, the wrapper code corresponding to Car::new makes the C++ invocation, new Car(). Later on, when you say in Perl space, $car->turn_left(), the appropriate C++ function is automatically called. If you want to supply CODE or PPCODE directives for C++ interfaces, you can refer to the object as THIS and to the class as CLASS.

This example has one hitch. It has no clue what's in the data type Car. Unlike SWIG, which quite unconcernedly treats a Car* like a void*, xsubpp expects help in the form of a typemap. Since we need to know the internal Perl API to create a typemap, we'll leave this issue unresolved until Chapter 20.