Intro to XS/C++

Doug Bell

Double Cluepon Software Corp.

Don't Panic

• XS has a reputation for being obtuse
  • Compared to Perl?
  • Lower-level
• Try it again for the first time

Just the Basics

• XS provides a way to call native libraries from Perl
• Probably C or C++
• XS for C is well-documented
  • http://perldoc.perl.org/index-internals.html
  • http://world.std.com/~swmcd/steven/perl/pm/xs/intro/
• XS for C++ less-so
  • Some mention in `perldoc perlxs`
  • http://www.johnkeiser.com/perl-xs-c++.html
  • C++ is a wonderful language for XS

Start with h2xs

• Build a bare XS module called MyModule
  • h2xs -A --skip-exporter -nMyModule
    • -A -- no AUTOLOAD
    • --skip-exporter -- no use Exporter
    • -nMyModule -- name MyModule
• Set appropriate Makefile.PL parameters
  • h2xs -L/opt/local/lib -lmylib
  • Much like the arguments to gcc/g++

What we have

lib/MyModule.pm

package MyModule;

use 5.014001;
use strict;
use warnings;

our @ISA = qw();

our $VERSION = '0.01';

require XSLoader;
XSLoader::load('MyModule', $VERSION);

# Preloaded methods go here.

1;

MyModule.xs

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

#include "ppport.h"

MODULE = MyModule               PACKAGE = MyModule

• Before "MODULE" -- C/C++
• After "MODULE" -- XS
• .xs files processed by xsubpp into C/C++
• XS covered later, some administrative details first...

C++ Edits to MyModule.xs

• Add 'extern "C"' around C headers

#ifdef __cplusplus
extern "C" {
#endif
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
#ifdef __cplusplus
}
#endif

• This prevents name-mangling

C++ typemap file

• http://www.cpan.org/authors/id/DMR/
• perlobject.map
• We'll add it to Makefile.PL later

typemap file

• typemap maps C/C++ types to/from Perl SV

# typemap
MyClass *       O_OBJECT

• O_OBJECT defined in perlobject.map

typemap file

MyClass *       O_MYCLASS

OUTPUT
O_MYCLASS
    sv_setref_pv( $arg, CLASS, (void*)$var );

INPUT
O_MYCLASS
    if ( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) ) {
        $var = ($type)SvIV((SV*)SvRV( $arg ));
    }
    else {
        warn( \"${Package}::$func_name() -- \
		$var not a blessed SV reference\" );
        XSRETURN_UNDEF;
    }

Makefile.PL

use 5.014001;
use ExtUtils::MakeMaker;
WriteMakefile(
    NAME              => 'MyModule',
    VERSION_FROM      => 'lib/MyModule.pm', # finds $VERSION
    PREREQ_PM         => {}, # e.g., Module::Name => 1.1
    ($] >= 5.005 ?     ## Add these new keywords supported since 5.005
      (ABSTRACT_FROM  => 'lib/MyModule.pm', # retrieve abstract from module
       AUTHOR         => 'Doug <madcityzen@gmail.com>') : ()),
    LIBS              => [''], # e.g., '-lm'
    DEFINE            => '', # e.g., '-DHAVE_SOMETHING'
    INC               => '-I.', # e.g., '-I. -I/usr/include/other'
        # Un-comment this if you add C files to link with later:
    # OBJECT            => '$(O_FILES)', # link all the C files too
    ### Add these for C++ support
    CC                => 'g++', # Override from Config
    LD                => 'g++', # Override from Config
    XSOPT             => '-C++',
    TYPEMAPS          => ['perlobject.map'],
);

Interface a C++ Class

#ifdef __cplusplus
extern "C" {
#endif
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
#ifdef __cplusplus
}
#endif

Interface a C++ Class

class Card {
    int value_;
    enum t_suit { SPADES, CLUBS, HEARTS, DIAMONDS } suit_;
    public:
        Card( int value, t_suit suit ) {
            value_ = value;
            suit_ = suit;
        }
        ~Card() { }
        int value() { return value_; }
        int suit() { return suit_; }
        void set_value( int value ) {
            value_ = value;
        }
        void set_suit( t_suit suit ) {
            suit_ = t_suit;
        }
};

Interface a C++ Class

MODULE = Card               PACKAGE = Card

Card *
Card::new( int suit, int value )

void
Card::DESTROY()

int
Card::value()

int
Card::suit()

void
Card::set_value( int value )

void
Card::set_suit( int suit )

typemap

Card *      O_OBJECT

• Card::new() gives us CLASS automatically
• Other Card::* knows it gets a Card * and calls it THIS
• All this comes from XSOPTS => '-C++',

Build and test

$ perl Makefile.PL && make test

• And you're done

More Difficult Interfaces

#include <vector>
class Deck {
    std::vector<Card> cards_;
    public:
        Deck() { }
        ~Deck() { }
        void add_card( Card card ) {
            cards_.push_back( card );
        }
        std::vector cards() {
            return cards_;
        }
};

More Difficult Interfaces

MODULE = Card               PACKAGE = Deck

Deck *
Deck::new()

void
Deck::DESTROY()

• Standard boilerplate
• Module turns into Card.so
• Package turns into package Deck;
• Include in Card.xs

Custom CODE:

void
Deck::add_card( suit, value )
    int suit
    int value
    CODE:
        Card card( suit, value );
        THIS->add_card( card );

• Change the interface of Deck
• CODE: is C/C++ code

Returning Arrays

AV *
Deck::cards()
    CODE:
        std::vector<Card> cards( THIS->cards() );
        std::vector<Card>::iterator iter( cards.begin() );
        RETVAL = newAV();               // create an array
        sv_2mortal( (SV*)RETVAL );      // "mortalize"
        for ( ; iter != cards.end(); iter++ ) {
            SV* card_sv( newSV(0) );    // create a scalar
            sv_setref_pv( card_sv, "Card", (void*)&*iter ); // bless
            av_push( RETVAL, card_sv );
        }
    OUTPUT:
        RETVAL

Thems The Basics

• Questions
• Comments
• Concerns
• Scathing Criticisms
• Bombastic Praise
• Moving on...

Memory Management with SVs

• Perl SVs are reference counted
• C++11 std::shared_ptr is reference counted
• Same techniques can be used to track SVs through C++
  • Good for C++ callbacks
  • POSIX-threaded applications
  • Avoid memory leaks
  • Type-safety with templates
  • Pointer can be used after we're done with it (ownership)

Building shared_sv

• The Required 4 methods for STL containers
  • Default (empty) Constructor
  • Copy constructor
  • Assignment operator
  • Destructor
• Mostly C++ code

Constructor(s)

• One for STL containers to create empty objects
• One for users to create new SVs

/** Default constructor needed for STL containers */
shared_sv() : p_(0), sv_(0) {};

/** Useful constructor */
shared_sv( void* p, std::string package )
    : p_(p), sv_( newSV(0) ) // Created with refcnt 1
{
    if ( sv_ == 0 ) return;
    sv_ = sv_setref_pv( sv_, package.c_str(), p_ );
}

Copy constructor

shared_sv( const shared_sv& that ) 
    : p_(that.p_), sv_(that.sv_)
{
    if ( sv_ == 0 ) return; // Don't do empty SVs
    // We can increment the refcount faster if we 
    // don't care about return value (void)
    SvREFCNT_inc_void( sv_ );
}

• Copying increments ref count
• Happens a lot inside STL containers
• Happens during method calls

Assignment operator

shared_sv& operator=( const shared_sv& that ) {
    if ( this == &that ) return *this; // Mandatory
    p_ = that.p_;
    if ( sv_ != 0 ) 
        SvREFCNT_dec( sv_ ); // Lose our SV
    sv_ = that.sv();
    if ( sv_ == 0 ) return *this;
    SvREFCNT_inc_void( sv_ ); // Gain their SV
    return *this;
}

• Assign into STL containers
  • vector[i] = new shared_sv(...);
• Also happens a lot during STL container internals

Destructor

~shared_sv() {
    if ( sv_ == 0 ) return;
    SvREFCNT_dec( sv_ );
}

• We're done, decrement our refcount
• When refcount is zero, the DESTROY() XS method is called
• Default DESTROY for XS/C++ is delete THIS

Usage

• In routines

shared_sv make_card( ) {
    // Card* card = new Card(); <- bad
    shared_sv ssv( new Card(), "Card" ); // <- good
    // We return a copy
    return ssv;
    // Copy means refcount incremented
}

• In containers

std::vector<shared_sv> cxx_array();
// Card* card = new Card(); <- bad
shared_sv ssv( new Card(), "Card" ); // <- good
cxx_array.push_back( ssv );
// cxx_array keeps a copy, refcount incremented

Helpful tips

• Keep little C/C++ inside .xs file
  • Sharing functions between .xs files is hairy
  • Make a static lib to link against
• Build a Perly interface in the XS if possible
  • C-style interfaces are not Perly
• Do most things in Perl
  • More stuff done in Perl, more flexibility you have
  • Pull routines out into Perl as long as interface remains Perly
• One directory for each XS package
  • Subdirectories of main XS package
  • Helps share code when in Perl

Docs for C++

• http://www.cplusplus.com/reference/
• http://www.parashift.com/c++-faq-lite/
• Effective C++, Effective STL, More Effective C++ by Scott Meyers
• C++ Coding Standards by Andrei Alexandrescu and Herb Sutter
  • Perl Best Practices for C++

The End!

• Slides: http://preaction.github.com/Perl/Intro-XS-CXX.html
• Code:
  • shared_sv.hpp

Slides are licensed under a CC-BY-SA 3.0 license.

Code is licensed under the Artistic License or GNU GPL v1.0 or later (the same terms as Perl itself).