API Design for C++

import “mydefs.h”,“unknown.idl”;

11.2.4 COM Automation

Component Object Model (COM) is a binary interface standard that allows objects to interact with each other via interprocess communication. COM objects specify well-defined interfaces that allow software components to be reused and linked together to build end-user applications. The technology was developed by Microsoft in 1993 and is still used today, predominantly on the Windows platform, although Microsoft now encourages the use of .NET and SOAP.

COM encompasses a large suite of technologies, but the part I will focus on here is COM Automation, also known as OLE Automation or simply Automation. This involves Automation objects (also known as ActiveX objects) being accessed from scripting languages to perform repetitive tasks or to control an application from script. A large number of target languages are supported, such as Visual Basic, JScript, Perl, Python, Ruby, and the range of Microsoft .NET languages.

A COM object is identified by a Universally Unique ID (UUID) and exposes its functionality via interfaces that are also identified by UUIDs. All COM objects support the IUnknown interface methods of AddRef(), Release(), and QueryInterface(). COM Automation objects additionally implement the IDispatch interface, which includes the Invoke() method to trigger a named function in the object.

The object model for the interface being exposed is described using an interface description language (IDL). IDL is a language-neutral description of a software component’s interface, normally stored in a file with an .idl extension. This IDL description can then be translated into various forms using the MIDL.EXE compiler on Windows. The generated files include the proxy DLL code for the COM object and a type library that describes the object model. The following sample shows an example of the Microsoft IDL syntax:

// Example.idl

[

object, uuid(d1420a03-d0ec-11b1-c04f-008c3ac31d2f),

]

interface ISomething : IUnknown

HRESULT MethodA([in] short Param1, [out] BKFST *pParam2);

HRESULT MethodB([in, out] BKFST *pParam1);

object, uuid(1e1423d1-ba0c-d110-043a-00cf8cc31d2f),

[

pointer_default(unique)

]

interface ISomethingElse : IUnknown

HRESULT MethodC([in] long Max,

[in, max_is(Max)] Param1[],

[out] long *pSize,

[out, size_is(, *pSize)] BKFST **ppParam2);

There is also a framework called Cross-Platform Component Object Model, or XPCOM. This is an open source project developed by Mozilla and used in a number of their applications, including the Firefox browser. XPCOM follows a very similar design to COM, although their components are not compatible or interchangeable.

11.2.5 CORBA

The Common Object Request Broker Architecture (CORBA) is an industry standard to allow software components to communicate with each other independent of their location and vendor. In this regard, it is very similar to COM: both technologies solve the problem of communication between objects from different sources and both make use of a language-neutral IDL format to describe each object’s interface.

CORBA is cross-platform with several open source implementations and provides strong support for UNIX platforms. It was defined by the Object Management Group in 1991 (the same group that manages the UML modeling language). CORBA offers a wide range of language bindings, including Python, Perl, Ruby, Smalltalk, JavaScript, Tcl, and the CORBA Scripting Language (IDLscript). It also supports interfaces with multiple inheritance versus COM’s single inheritance.

In terms of scripting, CORBA doesn’t require a specific automation interface as COM does. All CORBA objects are scriptable by default via the Dynamic Invocation Interface, which lets scripting languages determine the object’s interface dynamically. As an example of accessing CORBA objects from a scripting language, here is a simple IDL description and how it maps to the Ruby language.

// example.idl

interface myInterface

struct MyStruct { short value; };

s = MyInterface::MyStruct.new

// example.rb

require ‘myInteface’

s.value = 42

11.3 Adding Python Bindings With Boost Python

The rest of this chapter is dedicated to giving you a concrete understanding of how to create script bindings for your C++ API. I begin by showing you how to create Python bindings using the Boost Python libraries.

Python is an open source dynamically typed language designed by Guido van Rossum and first appeared in 1991. Python is strongly typed and features automatic memory management and reference counting. It comes with a large and extensive standard library, including modules such as os, sys, re, difflib, codecs, datetime, math, gzip, csv, socket, json, and xml, among many others. One of the more unusual aspects of Python is the fact that indentation is used to define scope, as opposed to curly braces in C and C++. The original CPython implementation of Python is the most common, but there are other major implementations, such as Jython (written in Java) and Iron Python (targeting the .NET framework). For more details on the Python language, refer to http://www.python.org/.

As already noted, Boost Python is used to define Python bindings programmatically, which can then be compiled to a dynamic library that can be loaded directly by Python. Figure 11.1 illustrates this basic workflow.

Figure 11.1 The workflow for creating Python bindings of a C++ API using Boost Python. White boxes represent files; shaded boxes represent commands.

11.3.1 Building Boost Python

Many Boost packages are implemented solely as headers, using templates and inline functions, so you only need to make sure that you add the Boost directory to your compiler’s include search path. However, using Boost Python requires that you build and link against the boost_python library, so you need to know how to build Boost.

The recommended way to build Boost libraries is to use the bjam utility, a descendant of the Perforce Jam build system. So first you will need to download bjam. Prebuilt executables are available for most platforms from http://www.boost.org/.

Building the boost libraries on a UNIX variant, such as Linux or Mac, involves the following steps:

% cd <boost-root-directory>

% ./bootstrap.sh - -prefix=<install-dir>

% ./bjam toolset=<toolset> install

The <toolset> string is used to define the compiler that you wish to build under, for example, “gcc,” “darwin,” “msvc,” or “intel.”

If you have multiple versions of Python installed on your machine, you can specify which version to use via bjam’s configuration file, a file called user-config.bjam that you should create in your home directory. You can find out more details about configuring bjam in the Boost.Build manual, but essentially you will want to add something like the following entries to your user-config.bjam file:

using python

: 2.6 # version

: /usr/local/bin/python2.6 # executable Path

: /usr/local/include/python2.6 # include path

: /usr/local/lib/python2.6 # lib path

On Windows, you can perform similar steps from the command prompt (just run bootstrap.bat instead of boostrap.sh). However, you can also simply download prebuilt boost libraries from http://www.boostpro.com/. If you use the prebuilt libraries, you will need to make sure that you compile your script bindings using the same version of Python used to compile the BoostPro libraries.

11.3.2 Wrapping a C++ API with Boost Python

Let’s start by presenting a simple C++ API, which I will then expose to Python. I’ll use the example of a phone book that lets you store phone numbers for multiple contacts. This gives us a manageable, yet non-trival, example to build upon throughout the chapter. Here’s the public definition of our phonebook API.

Note that this will let us demonstrate a number of capabilities, such as wrapping multiple classes, the use of STL containers, and multiple constructors. I will also take the opportunity to demonstrate the creation of Python properties in addition to the direct mapping of C++ member functions to Python methods.

The Person class is essentially just a data container: it only contains getter/setter methods that access underlying data members. These are good candidates for translating to Python properties. A property in Python behaves like a normal object but uses getter/setter methods to manage access to that object (as well as a deleter method for destroying the object). This makes for more intuitive access to class members that you want to behave like a simple data member while also letting you provide logic that controls getting and setting the value.

Now that I have presented our C++ API, let’s look at how you can specify Python bindings for it using boost::python. You will normally create a separate .cpp file to specify the bindings for a given module, where it’s conventional to use the same base filename as the module with a _wrap suffix appended, that is, I will use phonebook_wrap.cpp for our example. This wrap file is where you specify the classes that you want to expose and the methods that you want to be available on those classes. The following file presents the boost::python code necessary to wrap our phonebook.h API.

// phonebook_wrap.cpp

.add_property(“name”, &Person::GetName, &Person::SetName)

class_<Person>(“Person”)

.add_property(“home_number”, &Person::GetHomeNumber,

class_<PhoneBook>(“PhoneBook”)

.def(“size”, &PhoneBook::GetSize)

.def(“add_person”, &PhoneBook::AddPerson)

.def(“remove_person”, &PhoneBook::RemovePerson)

.def(“find_person”, &PhoneBook::FindPerson,

return_value_policy<reference_existing_object>())

Note that for the Person class, I defined two properties, called name and home_number, and I provided the C++ getter/setter functions to control access to those properties (if I only provided a getter method then the property would be read only). For the PhoneBook class, I defined standard methods, called size(), add_person(), remove_person(), and find_person(), respectively. I also had to specify explicitly how I want the pointer return value of find_person() to behave.

You can then compile the code for phonebook.cpp and phonebook_wrap.cpp to a dynamic library. This will involve compiling against the headers for Python and boost::python as well as linking against the libraries for both. The result should be a phonebook.so library on Mac and Linux or phonebook.dll on Windows. (Note: Python doesn’t recognize the .dylib extension on the Mac.) For example, on Linux:

g++ -c phonebook.cpp

g++ -c phonebook_wrap.cpp -I<boost_includes> -I<python_include>

g++ -shared -o phonebook.so phonebook.o phonebook_wrap.o -lboost_python -lpython

TIP

Make sure that you compile your script bindings with the same version of Python that your Boost Python library was built against.

At this point, you can directly load the dynamic library into Python using its import keyword. Here is some sample Python code that loads our C++ library and demonstrates the creation of Person and Phonebook objects. Note the property syntax for accessing the Person object, for example, p.name, versus the method call syntax for the PhoneBook members, for example, book.add_person().

# create the phonebook

# add one contact

# add another contact

# display number of contacts added (2)

print “No. of contacts =”, book.size()

11.3.3 Constructors

In our phonebook_wrap.cpp file, I didn’t specify constructors for the Person or PhoneBook classes explicitly. In this case, Boost Python will expose the default constructor for each class, which is why I was able to write:

However, note that in the C++ API, the Person class has two constructors, a default constructor and a second constructor that accepts a string parameter:

….

You can tell Boost Python to expose both of these constructors by updating the wrapping code for Person to specify a single constructor in the class definition and then list further constructors using the .def() syntax.

class_<Person>(“Person”, init<>())

.def(init<std::string>())

.add_property(“name”, &Person::GetName, &Person::SetName)

.add_property(“home_number”, &Person::GetHomeNumber,

Now you can create Person objects from Python using either constructor.

p = phonebook.Person(‘Martin’)

11.3.4 Extending the Python API

It’s also possible to add new methods to the Python API that don’t exist in the C++ API. This is used most commonly to define some of the standard Python object methods, such as __str__() to return a human-readable version of the object or __eq__() to test for equality.

In the following example, I have updated the phonebook_wrap.cpp file to include a static free function that prints out the values of a Person object. I then use this function to define the Person.__str__() method in Python.

// phonebook_wrap.cpp

#include <sstream>

static std::string PrintPerson(const Person &p)

std::ostringstream stream;

stream << p.GetName() << “: ” << p.GetHomeNumber();

return stream.str();

.add_property(“name”, &Person::GetName, &Person::SetName)

.add_property(“home_number”, &Person::GetHomeNumber,

.def(“__str__”, &PrintPerson)

….

This demonstrates the general ability to add new methods to a class. However, in this particular case, Boost Python provides an alternative way to specify the __str__() function in a more idiomatic fashion. You could define operator<< for Person and tell Boost to use this operator for the __str__() method. For example,

std::ostream &operator<<(std::ostream &os, const Person &p)

os << p.GetName() << “: ” << p.GetHomeNumber();

return os;

.add_property(“name”, &Person::GetName, &Person::SetName)

.add_property(“home_number”, &Person::GetHomeNumber,

.def(self_ns::str(self))

With this definition for Person.__str__() you can now write code like the following (entered at the interactive Python interpreter prompt, >>>):

>>> import phonebook

>>> p = phonebook.Person(‘Martin’)

>>> print p

Martin:

>>> p.home_number = ‘(123) 456-7890’

>>> print p

Martin: (123) 456-7890

While I am talking about extending the Python API, I will note that the dynamic nature of Python means that you can actually add new methods to a class at run time. This is not a Boost Python feature, but a core capability of the Python language itself. For example, you could define the __str__() method at the Python level, as follows:

return “Name: %s\nHome: %s” % (self.name, self.home_number)

def person_str(self):

# override the __str__ method for the Person class

phonebook.Person.__str__ = person_str

This will output the following text to the shell.

print p

Name: Martin

Home: (123) 456-7890

11.3.5 Inheritance in C++

Both C++ and Python support multiple inheritance, and Boost Python makes it easy to expose all of the base classes of any C++ class. I’ll show how this is done by turning the Person class into a base class (i.e., provide a virtual destructor) and adding a derived class called PersonWithCell, which adds the ability to specify a cell phone number. This is not a particularly good design choice, but it serves our purposes for this example.

virtual ~Person();

class PersonWithCell : public Person

explicit PersonWithCell(const std::string &name);

public:

PersonWithCell();

void SetCellNumber(const std::string &number);

std::string GetCellNumber() const;

You can then represent this inheritance hierarchy in Python by updating the wrap file as follows:

.add_property(“name”, &Person::GetName, &Person::SetName)

.add_property(“home_number”, &Person::GetHomeNumber,

class_<PersonWithCell, bases<Person> >(“PersonWithCell”)

.def(init<std::string >())

.add_property(“cell_number”, &PersonWithCell::GetCellNumber,

&PersonWithCell::SetCellNumber)

Now you can create PersonWithCell objects from Python as follows:

p = phonebook.PersonWithCell()

p.cell_number = ‘(123) 097-2134’

You can create classes in Python that derive from C++ classes that you’ve exposed with Boost Python. For example, the following Python program shows how you could create the PersonWithCell class directly in Python and still be able to add instances of this class to PhoneBook.

11.3.6 Cross-Language Polymorphism

class PyPersonWithCell(phonebook.Person):

def get_cell_number(self):

return self.cell

def set_cell_number(self, n):

self.cell = n

cell_number = property(get_cell_number, set_cell_number)

p = PyPersonWithCell()

p.cell_number = ‘(123) 097-2134’

Of course, the cell_number property on PyPersonWithCell will only be callable from Python. C++ will have no idea that a new method has been dynamically added to an inherited class.

It’s also important to note that even C++ virtual functions that are overridden in Python will not be callable from C++ by default. However, Boost Python does provide a way to do this if cross-language polymorphism is important for your API. This is done by defining a wrapper class that multiply inherits from the C++ class being bound as well as Boost Python’s wrapper class template. This wrapper class can then check to see if an override has been defined in Python for a given virtual function and then call that method if it is defined. For example, given a C++ class called Base with a virtual method, you can create the wrapper class as follows:

class BaseWrap : Base, wrapper<Base>

// check for an override in Python

if (override f = this->get_override(“f”))

return f();

// or call the C++ implementation

return this->Base::f();

Then you can expose the Base class as follows:

class_<BaseWrap, boost::non-copyable>(“Base”)

.def(“f”, &Base::f, &BaseWrap::default_f)

Boost Python also lets you create Python iterators based on STL iterator interfaces that you define in your C++ API. This lets you create objects in Python that behave more “Pythonically” in terms of iterating through the elements in a container. For example, you can add begin() and end() methods to the PhoneBook class that provide access to STL iterators for traversing through all of the contacts in the phone book.

11.3.7 Supporting Iterators

typedef std::vector<Person *> PersonList;

PersonList::iterator begin();

PersonList::iterator end();

With these additional methods, you can extend the wrapping for the PhoneBook class to specify the __iter__() method, which is the Python way for an object to return an iterator.

class_<PhoneBook>(“PhoneBook”)

.def(“size”, &PhoneBook::GetSize)

.def(“add_person”, &PhoneBook::AddPerson)

.def(“remove_person”, &PhoneBook::RemovePerson)

.def(“find_person”, &PhoneBook::FindPerson,

return_value_policy<reference_existing_object>())

.def(“__iter__”, range(&PhoneBook::begin, &PhoneBook::end));

Now, you can write Python code that iterates through all of the contacts in a PhoneBook object as follows:

book.add_person(phonebook.Person())

for person in book:

print person

11.3.8 Putting It All Together

Combining all of the features that I’ve introduced in the preceding sections, here is the final definition of the phonebook.h header and the phonebook_wrap.cpp boost::python wrapper.

virtual ~Person();

class PersonWithCell : public Person

explicit PersonWithCell(const std::string &name);

public:

PersonWithCell();

void SetCellNumber(const std::string &number);

std::string GetCellNumber() const;

typedef std::vector<Person *> PersonList;

PersonList::iterator begin() { return mList.begin(); }

PersonList::iterator end() { return mList.end(); }

// phonebook_wrap.cpp

#include <sstream>

std::ostream &operator<<(std::ostream &os, const Person &p)

os << p.GetName() << “: ” << p.GetHomeNumber();

return os;

static std::string PrintPersonWithCell(const PersonWithCell *p)

std::ostringstream stream;

stream << “Name: ” << p->GetName() << “, Home: ”;

stream << p->GetHomeNumber() << “, Cell: ”;

stream << p->GetCellNumber();

return stream.str();

.add_property(“name”, &Person::GetName, &Person::SetName)

.add_property(“home_number”, &Person::GetHomeNumber,

.def(self_ns::str(self))

bases<Person> >(“PersonWithCell”)

class_<PersonWithCell,

.add_property(“cell_number”, &PersonWithCell::GetCellNumber,

&PersonWithCell::SetCellNumber)

.def(“__str__”, &PrintPersonWithCell)

class_<PhoneBook>(“PhoneBook”)

.def(“size”, &PhoneBook::GetSize)

.def(“add_person”, &PhoneBook::AddPerson)

.def(“remove_person”, &PhoneBook::RemovePerson)

.def(“find_person”, &PhoneBook::FindPerson,

return_value_policy<reference_existing_object>())

.def(“__iter__”, range(&PhoneBook::begin, &PhoneBook::end));

The following sections will look at another example of creating script bindings for C++ APIs. In this case I will use the Simplified Wrapper and Interface Generator and I will use this utility to create bindings for the Ruby language.

11.4 Adding Ruby Bindings With Swig

Ruby is an open source dynamically typed scripting language that was released by Yukihiro “Matz” Matsumoto in 1995. Ruby was influenced by languages such as Perl and Smalltalk with an emphasis on ease of use. In Ruby, everything is an object, even types that C++ treats separately as built-in primitives such as int, float, and bool. Ruby is an extremely popular scripting language and is often cited as being more popular than Python in Japan, where it was originally developed. For more information on the Ruby language, see http://www.ruby-lang.org/.

SWIG works by reading the binding definition within an interface file and generating C++ code to specify the bindings. This generated code can then be compiled to a dynamic library that can be loaded directly by Ruby. Figure 11.2 illustrates this basic workflow. Note that SWIG supports many scripting languages. I will use it to create Ruby bindings, but it could just as easily be used to create Python bindings, Perl bindings, or bindings for several other languages.

Figure 11.2 The workflow for creating Ruby bindings of a C++ API using SWIG. White boxes represent files; shaded boxes represent commands.

11.4.1 Wrapping a C++ API with SWIG

I’ll start with the same phone book API from the Python example and then show how to create Ruby bindings for this interface using SWIG. The phone book C++ header looks like

bool IsEmpty() const;

int GetSize() const;

// we need the API header to compile the bindings

Let’s take a look at a basic SWIG interface file to specify how you want to expose this C++ API to Ruby.

// phonebook.i

%module phonebook

// pull in the built-in SWIG STL wrappings (note the ‘%’)

%include “std_string.i”

%include “std_vector.i”

bool IsEmpty() const;

int GetSize() const;

swig -c++ -ruby phonebook.i # creates phonebook_wrap.cxx

You can see that the interface file looks very similar to the phonebook.h header file. In fact, SWIG can parse most C++ syntax directly. If your C++ header is very simple, you can even use SWIG’s %include directive to simply tell it to read the C++ header file directly. I’ve chosen not to do this so that you have direct control over what you do and do not expose to Ruby.

Now that you have an initial interface file, you can ask SWIG to read this file and generate Ruby bindings for all the specified C++ classes and methods. This will create a phonebook_wrap.cxx file, which you can compile together with the C++ code to create a dynamic library. For example, the steps on Linux are

g++ -c phonebook_wrap.cxx -I<ruby-include-path>

g++ -c phonebook.cpp

g++ -shared -o phonebook.so phonebook_wrap.o phonebook.o -L<ruby-lib-path> -lruby

11.4.2 Tuning the Ruby API

This first attempt at a Ruby binding is rather rudimentary. There are several issues that you will want to address to make the API feel more natural to Ruby programmers. First off, the naming convention for Ruby methods is to use snake case instead of camel case, that is, add_person() instead of AddPerson(). SWIG supports this by letting you rename symbols in the scripting API using its %rename command. For example, you can add the following lines to the interface file to tell SWIG to rename the methods of the PhoneBook class.

%rename(“size”) PhoneBook::GetSize;

%rename(“add_person”) PhoneBook::AddPerson;

%rename(“remove_person”) PhoneBook::RemovePerson;

%rename(“find_person”) PhoneBook::FindPerson;

Recent versions of SWIG actually support an -autorename command line option to perform this function renaming automatically. It is expected that this option will eventually be turned on by default.

Second, Ruby has a concept similar to Python’s properties to provide convenient access to data members. In fact, rather elegantly, all instance variables in Ruby are private and must therefore be accessed via getter/setter methods. The %rename syntax can be used to accomplish this ability too. For example,

%rename(“name”) Person::GetName;

%rename(“name=”) Person::SetName;

%rename(“home_number”) Person::GetHomeNumber;

%rename(“home_number=”) Person::SetHomeNumber;

Finally, you may have noticed that I added an extra IsEmpty() method to the PhoneBook C++ class. This method simply returns true if no contacts have been added to the phone book. I’ve added this because it lets me demonstrate how to expose a C++ member function as a Ruby query method. This is a method that returns a boolean return value and by convention it ends with a question mark. I would therefore like the IsEmpty() C++ function to appear as empty? in Ruby. This can be done using either SWIG’s %predicate or %rename directives.

%rename(“empty?”) PhoneBook::IsEmpty;

With these amendments to our interface file, our Ruby API is starting to feel more native. If you rerun SWIG on the interface file and rebuild the phonebook dynamic library, you can import it directly into Ruby and write code such as

book = Phonebook::PhoneBook.new

puts “No. of contacts = #{book.size}”

Note the use of the p.name getter and p.name= setter, as well as the snake case add_person() method name.

11.4.3 Constructors

Our Person class has two constructors: a default constructor that takes no parameters and a non-default constructor that takes a std::string name. Using SWIG, you simply have to include those constructor declarations in the interface file and it will automatically create the relevant constructors in Ruby. That is, given the earlier interface file, you can already do:

p = Phonebook::Person.new(‘Genevieve’)

In general, method overloading is not quite as flexible in Ruby as it is in C++. For example, SWIG will not be able to disambiguate between overloaded functions that map to the same types in Ruby, for example, a constructor that takes a short and another that takes an int or a constructor that takes a pointer to an object and another that takes a reference to the same type. SWIG does provide a way to deal with this by letting you ignore a given overloaded method (using %ignore) or renaming one of the methods (using %rename).

11.4.4 Extending the Ruby API

SWIG lets you extend the functionality of your C++ API, for example, to add new methods to a class that will only appear in the Ruby API. This is done using SWIG’s %extend directive. I will demonstrate this by adding a to_s() method to the Ruby version of our Person class. This is a standard Ruby method used to return a human-readable representation of an object, equivalent to Python’s __str__() method.

// phonebook.i

%module phonebook

#include <sstream>

#include <iostream>

%extend {

std::string to_s() {

std::ostringstream stream; stream << self->GetName() << “: ”; stream << self->GetHomeNumber(); return stream.str();

Using this new definition for our Person binding, you can write the following Ruby code:

puts p

The puts p line will print out the Person object using our to_s() method. In this case, this results in the following output:

Martin: (123) 456-7890

11.4.5 Inheritance in C++

As with the constructor case just given, there’s nothing special that you have to do to represent inheritance using SWIG. You simply declare the class in the interface file using the standard C++ syntax. For example, you can add the following PersonWithCell class to our API:

virtual ~Person();

class PersonWithCell : public Person

explicit PersonWithCell(const std::string &name);

public:

PersonWithCell();

void SetCellNumber(const std::string &number);

std::string GetCellNumber() const;

Then you can update the SWIG interface file as follows:

// phonebook.i

%rename(“name”) Person::GetName;

%rename(“name=”) Person::SetName;

%rename(“home_number”) Person::GetHomeNumber;

%rename(“home_number=”) Person::SetHomeNumber;

virtual ~Person();

%rename(“cell_number”) PersonWithCell::GetCellNumber;

%rename(“cell_number=”) PersonWithCell::SetCellNumber;

class PersonWithCell : public Person

explicit PersonWithCell(const std::string &name);

public:

PersonWithCell();

void SetCellNumber(const std::string &number);

std::string GetCellNumber() const;

You can then access this derived C++ class from Ruby as follows:

p = Phonebook::PersonWithCell.new

p.cell_number = ‘(123) 097-2134’

Ruby supports only single inheritance, with support for additional mixin classes. C++ of course supports multiple inheritance. Therefore, by default, SWIG will only consider the first base class listed in the derived class: member functions in any other base classes will not be inherited. However, recent versions of SWIG support an optional -minherit command line option that will attempt to simulate multiple inheritance using Ruby mixins (although in this case a class no longer has a true base class in Ruby).

11.4.6 Cross-Language Polymorphism

By default, if you override a virtual function in Ruby you will not be able to call the Ruby method from C++. However, SWIG gives you a way to enable this kind of cross-language polymorphism via its “directors” feature. When you enable directors for a class, SWIG generates a new wrapper class that derives from the C++ class as well as SWIG’s director class. The director class stores a pointer to the underlying Ruby object and works out whether a function call should be directed to an overridden Ruby method or the default C++ implementation. This is analogous to the way that Boost Python supports cross-language polymorphism. However, SWIG creates the wrapper class for you behind the scenes: all you have to do is specify which classes you want to create directors for and then enable the directors feature in your %module directive. For example, the following update to our interface file will turn on cross-language polymorphism for all our classes:

%module(directors=“1”) phonebook

#include <sstream>

%feature(“director”);