Doing something on shared library initialization

January 20, 2005

Note, this was written in 2005. Many things in C++ have changed since then, and I had less understanding of C++ at the time as well. This article describes a quick and easy solution we came up with in The VOS project at the time.

Newer versions of C++ (C++11/14, C++17, C++20) add many new features to control constant/compile time evaluation and initialization, and to support static initialization better. I have not revisited anythnig in this note with newer C++ features.

A few more recent resources on this topic are:


For convenience, maintainability and clean interfaces, it is sometimes desirable for a dynamically linked library to perform some initialization work before the execution of the main program. Unfortunately, the behaviour of C++, and the dynamic linker (most notable on Mac OSX) can cause such initialization to be delayed. This brief memo considers some possible solutions that can be used in C++, concluding with one best solution.

The problem

VOS is a network-distributed object system imprementation, in which objects can be extended by objects implementing specific "types" or interfaces for those objects. The type implementations are generated by a (typically) global factory according to a string identifying the type. We wanted to make it easy for the user to add types to his application simply by linking to the shared library defining them, without worrying about registering the type with the factory on program initialization. This means we need some code to be automatically executed at program startup, before main() is entered.

Possible solutions

Many dynamic linkers call a special function when a library is loaded. Linux's ld calls _init, and Windows calls DllMain (Though you can specify alternate names for these, they take platform specific arguments, so you would need to define both functions). I have found this method to be complex. GCC says that such functions need to be defined with __attribute__ ((constructor)) prepended but that doesn't seem to do much. Each linker uses a completely different init function convention, requiring you to anticipate all possible platforms for your code. Furthermore, you cannot be sure that the library will be loaded when your program is (see below for a way to force the library to be loaded).

(you can use a diferent name for _init by passing the -init name option to Linux ld)

So let's do it using just C++. We will simply define a static object, which does what we want in its constructor.

For example, this is a simple class which registers a generator callback with a global (static) "factory" object in its constructor:

class ObjectGenerator {
    ObjectGenerator() {
    static Object* generate() {
        return new Object();

By creating a static instance of this class inside the library, we can try to get the registration to happen on program initialization:

static ObjectGenerator globalStaticObjectGeneratorInstance;

More Problems!

But there is a big problem with this: globalStaticObjectGeneratorInstance's constructor does not seem to be called at startup, (first noted on Mac OSX and Windows, not initially noted on Linux during development.) It turns out that the static instance is not actually initialized when the library is loaded, or the program starts, a static value in C++ might not be initialized until it is first used (i.e. a function called, or other symbol referenced). (However, under some conditions, it seems to happen, which might lead you to assume it is standard behavior.) Therefore our desired action (e.g. generator registration) will not be done before entering main(). It will only be initialized when used or otherwised referenced.

Our solution was to add this bit of code to a header file included by the program: redeclare the static instance as extern, then actually make a reference to it, which forces the library to be loaded if it is not, and for the static object to be created:

class ObjectGenerator;
extern ObjectGenerator globalStaticObjectGeneratorInstance;
static ObjectGenerator& localObjectGeneratorReference = globalStaticObjectGeneratorInstance;

I don't know if this is garaunteed by the C++ language to work, but it seems to work with currently tested compilers. (GCC on Linux, MacOSX and MinGW on Windows.)


So it turns out there are only two working solutions: to use the library initialization functions specific to each platform, or to use a static object, then somehow reference library symbols in our main program, thereby forcing the linker to finish loading the library and initializing a static object. Since it simply uses the C++ language, I like the second method; it ought to be completely portable as well. The only downside is that you must include the local reference in your program, which means that you cannot simply link shared libraries to the program, you also have to modify the program code to reference the library.

You can hide this static-object trick in some macros if you want, which is what we do for VOS (DLLEXPORT is a macro for the annoying Windows DLL export attributes, or empty on other platforms):

    Use these macros to define a static registration class for
    a metaobject.  This lets you register metaobject factories automatically
    when your library is loaded.

    You must also use the REGISTERS_METAOBJECT_FACTORIES macro in a
    public header file as well.

            Site::addLocalMetaObjectFactory(typeid(Example).name(), &LocalExample::new_LocalExample);
            Site::addLocalMetaObjectFactory(typeid(LocalExample).name(), &LocalExample::new_LocalExample);
            Site::addLocalMetaObjectFactory("example:example", &LocalExample::new_LocalExample);

            Site::addRemoteMetaObjectFactory(typeid(Example).name(), "example:example", &RemoteExample::new_RemoteExample);
            Site::addRemoteMetaObjectFactory(typeid(RemoteExample).name(), "example:example", &RemoteExample::new_RemoteExample);
            Site::addRemoteMetaObjectFactory("example:example", "example:example", &RemoteExample::new_RemoteExample);

      If your metaobject does not need seperate Local and Remote behavior,
      you only need one class, for which you can register the same remote
      and local factory.

      @param cl A symbol that uniquely identifies this registration (e.g. use
      the MetaObject class name)
// @{
    class Register##cl {                           \
    public:                                        \
        Register##cl()                             \

        }                                          \
    };                                             \
    DLLEXPORT Register##cl Register##cl##_globalstatic;
// @}


/** Alternate macro for registering extender factories.
    Use this macro when you want to use the same MetaObject class for
    both local and remote objects, and don't need to do anything special
    at registration.  It creates a registration class named from
    a namespace and class name, containing a constructor which registers
    the same factory function for local and remote metaobject creation.

    You must also use the REGISTERS_METAOBJECT_FACTORIES macro in a
    public header file as well, using <ns>_<cl> as its argument (see below)

    @param ns   Namespace
    @param cl   Class name
    @param type Type string, should be the same string that getVOSType()
    @param factfn Static method that returns an instance of your class (as
        a VOS::MetaObject*), given a "super object" (of type VOS::VobjectBase*)
        and a type string.

    For example, imagine you have a metaobject class called ExampleClass.
    It is in a namespace called EG.  It might be declared in a header file like
        #include <vos/vos/vos.hh>

        namespace EG {
            class ExampleClass : public VOS::MetaObject {
                ExampleClass(VOS::VobjectBase* s);
                VOS::MetaObject* new_ExampleClass(VOS::VobjectBase* s, const std::string& t) {
                   return new ExampleClass(s);

    Somewhere in the definition (i.e. in your ".cc" or ".cpp" file), include
    this macro call:
        REGISTER_METAOBJECT_FACTORIES(EG, ExampleClass, "example:example", &EG::ExampleClass::new_ExampleClass)

    Now to the public header file, add this:
#define REGISTER_METAOBJECT_FACTORIES(ns, cl, type, factfn) \
    class Register##ns##_##cl { \
    public: \
        Register##ns##_##cl() { \
            Site::addLocalMetaObjectFactory(typeid(ns::cl).name(), factfn); \
            Site::addLocalMetaObjectFactory(type, factfn); \
            Site::addRemoteMetaObjectFactory(typeid(ns::cl).name(), type, factfn); \
            Site::addRemoteMetaObjectFactory(type, type, factfn); \
        } \
    }; \
    DLLEXPORT Register##ns##_cl Register##ns##_cl##_globalstatic;

/** You must use this macro in a public header file for every use of
 *  to the registration cleass, forcing the dynamic library loader to
 *  initialize it)
 * @param cl    Class name: use the same argument you used in defining the
 *              factory registration class.
    class Register##cl; \
    extern DLLIMPORT Register##cl Register##cl##_globalstatic; \
    static Register##cl &Register##cl##_localref = Register##cl##_globalstatic;