3. The Solution
Prev   Next

3. The Solution

3.1. extern "C"

C++ has a special keyword to declare a function with C bindings: extern "C". A function declared as extern "C" uses the function name as symbol name, just as a C function. For that reason, only non-member functions can be declared as extern "C", and they cannot be overloaded.

Although there are severe limitations, extern "C" functions are very useful because they can be dynamically loaded using dlopen just like a C function.

This does not mean that functions qualified as extern "C" cannot contain C++ code. Such a function is a full-featured C++ function which can use C++ features and take any type of argument.

3.2. Loading Functions

In C++ functions are loaded just like in C, with dlsym. The functions you want to load must be qualified as extern "C" to avoid the symbol name being mangled.

Example 1. Loading a Function

main.cpp:

#include <iostream>
#include <dlfcn.h>

int main() {
    using std::cout;
    using std::cerr;

    cout << "C++ dlopen demo\n\n";

    // open the library
    cout << "Opening hello.so...\n";
    void* handle = dlopen("./hello.so", RTLD_LAZY);
    
    if (!handle) {
        cerr << "Cannot open library: " << dlerror() << '\n';
        return 1;
    }
    
    // load the symbol
    cout << "Loading symbol hello...\n";
    typedef void (*hello_t)();

    // reset errors
    dlerror();
    hello_t hello = (hello_t) dlsym(handle, "hello");
    const char *dlsym_error = dlerror();
    if (dlsym_error) {
        cerr << "Cannot load symbol 'hello': " << dlsym_error <<
            '\n';
        dlclose(handle);
        return 1;
    }
    
    // use it to do the calculation
    cout << "Calling hello...\n";
    hello();
    
    // close the library
    cout << "Closing library...\n";
    dlclose(handle);
}

hello.cpp:

#include <iostream>

extern "C" void hello() {
    std::cout << "hello" << '\n';
}

The function hello is defined in hello.cppas extern "C"; it is loaded in main.cpp with the dlsym call. The function must be qualified as extern "C" because otherwise we wouldn't know its symbol name.

Warning

There are two different forms of the extern "C" declaration: extern "C" as used above, and extern "C" { … } with the declarations between the braces. The first (inline) form is a declaration with extern linkage and with C language linkage; the second only affects language linkage. The following two declarations are thus equivalent: 

extern "C" int foo;
extern "C" void bar();

and 

extern "C" {
     extern int foo;
     extern void bar();
}

As there is no difference between an extern and a non-extern function declaration, this is no problem as long as you are not declaring any variables. If you declare variables, keep in mind that 

extern "C" int foo;

and 

extern "C" {
    int foo;
}

are not the same thing.

For further clarifications, refer to [ISO14882], 7.5, with special attention to paragraph 7, or to [STR2000], paragraph 9.2.4.

Before doing fancy things with extern variables, peruse the documents listed in the see also section.

3.3. Loading Classes

Loading classes is a bit more difficult because we need an instance of a class, not just a pointer to a function.

We cannot create the instance of the class using new because the class is not defined in the executable, and because (under some circumstances) we don't even know its name.

The solution is achieved through polymorphism. We define a base, interface class with virtual members in the executable, and a derived, implementation class in the module. Generally the interface class is abstract (a class is abstract if it has pure virtual functions).

As dynamic loading of classes is generally used for plug-ins — which must expose a clearly defined interface — we would have had to define an interface and derived implementation classes anyway.

Next, while still in the module, we define two additional helper functions, known as class factory functions. One of these functions creates an instance of the class and returns a pointer to it. The other function takes a pointer to a class created by the factory and destroys it. These two functions are qualified as extern "C".

To use the class from the module, load the two factory functions using dlsym just as we loaded the hello function; then, we can create and destroy as many instances as we wish.

Example 2. Loading a Class

Here we use a generic polygon class as interface and the derived class triangle as implementation.

main.cpp:

#include "polygon.hpp"
#include <iostream>
#include <dlfcn.h>

int main() {
    using std::cout;
    using std::cerr;

    // load the triangle library
    void* triangle = dlopen("./triangle.so", RTLD_LAZY);
    if (!triangle) {
        cerr << "Cannot load library: " << dlerror() << '\n';
        return 1;
    }

    // reset errors
    dlerror();
    
    // load the symbols
    create_t* create_triangle = (create_t*) dlsym(triangle, "create");
    const char* dlsym_error = dlerror();
    if (dlsym_error) {
        cerr << "Cannot load symbol create: " << dlsym_error << '\n';
        return 1;
    }
    
    destroy_t* destroy_triangle = (destroy_t*) dlsym(triangle, "destroy");
    dlsym_error = dlerror();
    if (dlsym_error) {
        cerr << "Cannot load symbol destroy: " << dlsym_error << '\n';
        return 1;
    }

    // create an instance of the class
    polygon* poly = create_triangle();

    // use the class
    poly->set_side_length(7);
        cout << "The area is: " << poly->area() << '\n';

    // destroy the class
    destroy_triangle(poly);

    // unload the triangle library
    dlclose(triangle);
}

polygon.hpp:

#ifndef POLYGON_HPP
#define POLYGON_HPP

class polygon {
protected:
    double side_length_;

public:
    polygon()
        : side_length_(0) {}

    virtual ~polygon() {}

    void set_side_length(double side_length) {
        side_length_ = side_length;
    }

    virtual double area() const = 0;
};

// the types of the class factories
typedef polygon* create_t();
typedef void destroy_t(polygon*);

#endif

triangle.cpp:

#include "polygon.hpp"
#include <cmath>

class triangle : public polygon {
public:
    virtual double area() const {
        return side_length_ * side_length_ * sqrt(3) / 2;
    }
};


// the class factories

extern "C" polygon* create() {
    return new triangle;
}

extern "C" void destroy(polygon* p) {
    delete p;
}

There are a few things to note when loading classes:

  • You must provide both a creation and a destruction function; you must not destroy the instances using delete from inside the executable, but always pass it back to the module. This is due to the fact that in C++ the operators new and delete may be overloaded; this would cause a non-matching new and delete to be called, which could cause anything from nothing to memory leaks and segmentation faults. The same is true if different standard libraries are used to link the module and the executable.

  • The destructor of the interface class should be virtual in any case. There might be very rare cases where that would not be necessary, but it is not worth the risk, because the additional overhead can generally be ignored.

    If your base class needs no destructor, define an empty (and virtual) one anyway; otherwise you will have problems sooner or later; I can guarantee you that. You can read more about this problem in the comp.lang.c++ FAQ at http://www.parashift.com/c++-faq-lite/, in section 20.

Prev   Next
2. The Problem Home 4. Source Code