2.2.1   Parameters

Parameters of all primitive types are automatically handled. Class types need to be registered.

For class types, derived->base conversions are handled. In the case of a polymorphic type, base->derived conversions are also considered, based on the dynamic type of the parameter.

2.2.2   Return Values

Again, primitive types are automatically converted and class types need to be registered.

Class types can be returned by value, or held in a smart pointer. If returned by value, the object will be copied into a new instance. If a smart pointer is returned, the smart pointer will be copied and held in a new instance.

The return type is considered to be a smart pointer iff it has an overload of get_pointer() that returns a raw pointer to a class type. In other words, given that x is a smart pointer:

*get_pointer(x)

Must be well formed, and the type of that expression is considered the pointee type that is converted to the target language.

When references or pointers are returned, an ownership strategy need to be explicitly specified. This is to prevent dangling references and leaked objects. The ownership strategy is specified as the call policy parameter in the def() call.

def("f", &f, adopt(result)) // Manage the ownership over the returned pointer.
def("f", &f, reference_existing(result)) // Reference an existing object.
def("f", &f, internal_reference(result, _1)) // Returns a reference to something inside
                                             // the object given as parameter one, make sure
                                             // that object doesn't disappear leaving
                                             // a dangling reference.

Notice how placeholders are used to indicate which elements are involved.

2.3.1   Constructors

template<class A0 = /* implementation defined */, ..., class AN = /* implementation defined */>
struct init
{
    init();
    ...
};

Exposing constructors is done by calling def(), passing an instance of init<> with the desired constructor signature:

class_<X>("X")
    .def(init<>())
    .def(init<int, int>())

Creates a wrapper for the class type X, with a default constructor and a constructor taking two int parameters.

2.3.2   Member Functions

Member functions are exposed using one of the class_<>::def() overloads. The parameters are exactly the same as with the global def() described in the previous section.

For example:

class_<X>("X")
    .def("f", &f)

Will expose the class X with a single member function f.

2.3.3   Holder Types

Sometimes an interface passes instances of a class managed by smart pointers. In these cases it is important to be able to pass instances created in the target language environment to functions expecting a smart pointer.

void f(std::auto_ptr<X> const&);

To handle this we specify that our class instances are to be held with std::auto_ptr<X>:

class_<X, std::auto_ptr<X> >("X")

Now instances of X created in the target language can be safely passed to wrapped functions that expect a std::auto_ptr<X>. Note that boost::shared_ptr is a special case: even without specifying a holder type, any instance of X in the target language can be passed to wrapped functions accepting a boost::shared_ptr<X> by value or const reference. The shared_ptr is constructed with a special deleter that manages the target language object.

2.3.4   Inheritance

To indicate inheritance relationships the function type syntax is used. This was choosen to emulate the Python class declaration syntax. Indicating an inheritance relationship will register the relationship in a cast-graph, with derived->base, and possibly base->derived (if the registered class is polymorphic) conversions . The derived class will also automatically inherit any registered member functions from it's base.

For example:

class_<Derived(Base)>("Derived")

Multiple inheritance is exposed by simply adding more argument types to the function type:

class_<Derived(Base1, Base2)>("Derived")

2.3.5   Overridable Virtual Functions

To be able to expose overridable virtual functions for a class T without being intrusive on the exposed class, we need to define a wrapper-class. This class must derive from polymorphic<T> and implement virtual dispatch overrides, as well as default implementation functions for every virtual function.

A typical wrapper-class for a class Base will look something like this:

struct Base
{
    virtual int f() { return 0; }
}

struct BaseWrap : polymorphic<Base>
{
    int f()
    {
        if (override f = this->find_override("f"))
            return f();
        else
            return Base::f();
    }

    int default_f()
    {
        return Base::f();
    }
};

The virtual dispatch override looks if there is an override with the given function name in the target language representation of the instance. If there is one it is called using operator(). If there is no overload, the default implementation in Base is called instead.

default_f is needed for when there is actually an override defined in the target language, but we want to call the base class function statically anyway. This happens when virtual overrides wants to call their base implementation:

class Derived(Base):
    def f():
        return Base.f(self) + 10

If not for default_f, this would call the virtual function ending up in an infinite loop.

To expose the class above and its virtual function f, we use class_ like this:

class_<BaseWrap>("Base")
    .def("f", &Base::f, &BaseWrap::default_f)

Now instances of derived classes defined in a target language can be passed in place of an Base.

int g(Base& x)
{
    return x.f();
}

...

def("g", &g);

Python code:

class Derived(Base):
    def f():
        return 10

g(Derived())    Returns 10

Lua code:

class "Derived" (Base)
    function Derived:f()
        return 10
    end

g(Derived())    Returns 10

2.3.6   Operators

Boost.Langbinding makes use of expression templates to make the syntax for exposing operators as intuitive as possible.

class_<X>("X")
    .def(self + self)
    .def(self + int())
    .def(int() + self)

template<class T>
struct other
{
    other();
};

We support most of C++'s operators. How many of these that are actually supported by a target language can vary. Normally at least the binary arithmetic operators are supported.

Binary operators:

+   -   *   /   %   ^   &   |   &&  ||

In place operators:

+=  -=  *=  /=  %=  ^=  &=  |=  ++  --

Unary operators:

-   ~   *   !

3.2.1   Module Creation

b.visit(backend::module const& m);
b.leave(backend::module const& m);

3.2.2   Function Creation

b.visit(backend::function<B> const& f);
b.leave(backend::function<B> const& f);

This interface is used both for functions bound at module scope and for member functions bound within classes. Functions visited while a class is being visited should be treated as member functions.

Typically, upon visiting a function the Module Builder will want to create a new callable object (in its target language) that, when called, invokes f

B::function_result result = f(a, i);

where a is an object of type B::argument_package and i is an object of type B::interpreter.

typedef B::function_result R;

typedef B::argument_package A;

typedef B::interpreter;

3.2.3   Class Creation

b.visit(backend::class_ const& c);
b.leave(backend::class_ const& c);

A unique integer id has been allocated to each class wrapped by the front-end from the sequence of numbers starting with zero. The id can be accessed via:

c.id()

The backend will typically want to create an appropriately-named class object in the target module. The integer id can be used as an index into a table of class objects.

In a target language with multiple interpreter states, there would be a separate table for each state.

If target language interpreters can be destroyed and reconstituted (e.g. with PyFinalize), it may be neccessary to delete the references in table so the target language can release the class objects.