The impact of C++ templates on library ABI

Using templates in final executables only

A one particular way in which the problem could be avoided is to limit the template instantiation to a single executable. For practical reasons, that executable would supposedly be the final program executable, allowing the programmer to use templates freely and all the libraries to use them equally.

This can be achieved through making all the implementation using templates… a template as well. For example, consider the following code:

#include <vector>

class C
{
public:
        int f();

        // ...
};

int C::f()
{
        std::vector<int> value_vector;

        // ...
}

Here function f() from class C uses a std::vector<int> internally. In order to avoid local instantiation of the vector, we need to make the class C a template class. In this particular case, we can achieve an additional benefit from that — allowing the user to specify the allocator for value_vector:

#include <memory>
#include <vector>

template < class allocator = std::allocator<void> >
class C
{
public:
        int f()
        {
                typedef typename allocator::template rebind<int>
                        ::other alloc_type;
                std::vector<int, alloc_type> value_vector;

                // ...
        }
};

This way, as long as all classes using C are templates as well, the only template instantiation will take place in the final executable where the last template class is used. Of course, this has many implications for quite a little benefit. Most importantly:

• all template classes have to be used along with template parameters; instead of C, one has to use C<>;
• all template classes have to make the implementation public, and start to suffer from all template-related issues explained here;
• the code generation is deferred to the final executable. Code duplication occurs, shared libraries no longer serve a purpose and compiling the program becomes time- and memory-consuming.

Just as a note, the fore-mentioned approach can be used when there is no logical use for a template as well. An unused template parameter can be introduced then:

template <int unused = 0>
class C
{
        // ...
};

Using custom types in shared library templates

An alternate and possibly better approach is to prevent non-local instantiations of a particular template specializations through scoping of the types used in them.

Please consider the following example:

#include <list>

// class C is a public class provided by the library

void f()
{
        std::list<C> l;

        // ...
}

Here, the std::list<C> template is instantiated. However, the type C is part of the public library API and an API consumer may want to create a list of that type as well. In order to avoid the list being instantiated twice, the library may replace C with a local-scope derived class:

#include <list>

namespace
{
        class C_ : public C
        {
                // ...
        };
};

void f()
{
        std::list<C_> l;

        // ...
}

Since C and C_ are distinct types, std::list<C_> will instantiate a different specialization than std::list<C>. And as C_ is limited to the local scope, no consumer should be able to
create a list of that type.

Using inline methods and functions

There is one more solution which I am ought to mention, yet its use is limited and it is not guaranteed to work at all. The one remaining way of preventing multiple instantiations is to enforce inline instantiations of template methods.

This approach has a few limitations. Firstly, it requires modifying the template itself, so it won’t work with external templates, like fore-mentioned std::list. Additionally, since the compiler is free to ignore the inline keyword at will, this solution may only work partially or not work at all.

For completeness, I will present an example:

template <class T>
class C
{
        T sth;

public:
        inline T& get()
        {
                return sth;
        }

        inline void set(T& new_val)
        {
                sth = new_val;
        }
};

The above code uses the inline keyword extensively, hoping that the compiler will inline all the method calls rather than instantiating them as separate methods. If it succeeds for all of the methods, external instantiations will not have anything to collide with.

Explicitly instantiating opaque templates

One particular solution which solves the issue completely is to keep the implementation completely opaque, and force the compiler to explicitly instantiate necessary templates. However, a very important disadvantage of this solution is that the possible uses of the template are limited to the ones provided by the library.

For an example, please consider we’re having a MyList<T> container which works similarly to std::list<T>. In order to make the list implementation opaque, the header files contain only the interface of MyList<T>:

template <class T>
class MyList
{
        struct priv_type;
        priv_type* priv;

public:
        // ...
};

As you can see in the above example, the PImpl (private implementation) idiom is used there to hide the private class members. That kind of PImpl implementation does not make sense with regular templates, since the private members would have to be explicitly listed along with the implementation. However, in this case we are keeping the implementation private.

The implementation along with the supported instantiations is provided in the source file of the library:

#include "mylist"

template class MyList<int>;
template class MyList<double>;
template class MyList<void*>;

// ...

With the above declarations, followed by the method and struct priv_type implementations will result in compiler outputting the template code for int, double and void* types. That code will be placed in the shared library, and made available for the consumers of the shared library.

Now, if a consumer uses MyList<int> and links to the shared library, it will use the opaque implementation from the library. Alike with regular functions, any ABI-safe changes will be propagated to the programs; and ABI-unsafe will result in necessity of rebuilding them, propagated through SONAME change.

However, if the consumer decides to use MyList<char>, the compiler will no longer be able to satisfy that requirement. The linker will refuse to link the program because of no implementation of MyList<char> methods.

Using common base classes and functions

Sadly, the fore-mentioned approach limits the possible uses of the template to a predefined parameter sets. This may be acceptable in very specific cases but usually it just invalidates the whole point of using templates.

An alternative approach is to use a partially opaque implementation, with the opaque being subject to easy implementation changes, and the public behaving like a regular template. This could be accomplished in a number of ways.

One of them is to develop a common, opaque base class which performs the most important tasks in a type-agnostic way and a derived template class which wraps the former in a nice API. For example, consider a pointer list like the following:

template <class T>
class PointerList;

template <>
class PointerList<void>
{
        struct priv_data;
        priv_data* priv;

public:
        // ...
};

template <class T>
class PointerList
        : private PointerList<void>
{
public:
        // ...
};

The pointer list template is first specialized for the void* type. That specialization uses a PImpl idiom, private code and explicit instantiation (in the source file) to provide an opaque implementation of void* pointer list. On top of that, a public generic pointer list template is built.

With such a solution, the most important parts of implementation (in this case that would be the list handling code) are kept opaque, and thus changes in that code are propagated the usual way. The remaining public parts (in this case, that part would probably just cast types) suffer the regular issues with template classes.

It should be noted that the example presented above was very optimistic. Usually, providing a common opaque implementation is a more demanding task. Sometimes even it is not possible to split out a common amount of code for the base class, and only small pieces of code could be considered common. In these cases, the presented approach may not be beneficial at all.

The –as-needed problem

The fore-mentioned interface versioning technique requires the program using templates to link against a shared library where the version is defined. This becomes problematic if the template class does not use opaque implementation in the used code (i.e. all methods used by a particular consumer are defined in the template) and the –as-needed GNU linker option is used.

The intent of that option is to link the program executable only with those libraries which it uses directly. Although this often is advantageous and thus the option gained popularity, it thwarts our plans. Because the code using the templates does not call any function from the library we are forcing it to link, the linker will simply skip that library. Effectively, the ABI link will be broken, and interface changes from the library won’t be propagated to template consumers.

Although this specific problem could supposedly be worked around through disabling that option, that is not really feasible in this case. Most importantly, the task of disabling it would either need to be done by the library consumers directly (effectively, making it unlikely to happen) or handled through an external -config application which will hurt cross-compilation.

To cover the topic completely, I’ll note that such a solution would first have to check whether –as-needed is actually enabled. And due to the specific synopsis of -Wl compiler option, finding that would be a semi-difficult task (and different compilers will have different options). Then, it would have to add -Wl,–no-as-needed, the relevant libraries and re-enable -Wl,–as-needed.

Since that thing is neither easy to implement, nor portable, and we can’t forget that other (future) linkers can inhibit similar behavior using different options or even unconditionally, I believe we should look for another solution. One which works around the actual issue rather than trying to disable the feature exposing it.

Using dummy symbols to enforce linking

As mentioned earlier, the reason why linker silently ignores our library is that the program doesn’t actually use any symbol from it. So, in order to work around that, we simply need to define a dummy symbol and use it. Although that may look simple at first, we should give it some thought.

First of all, considering that the symbol has no real meaning, we should try hard to avoid unnecessary impact on the code, both in terms of performance and its size. Preferably, it should be as short as possible, and it should appear on unused (or likely-unused) code paths. However, we should also make sure that the code will actually be reachable — and thus the compiler won’t optimize it out.

For example, an obvious solution seems to add a dummy() method to our template class, and access the symbol there. Sadly, since the method is never actually used, the compiler doesn’t even instantiate it. After some thinking, you may reach a consensus that the only safe place for the call is in the constructor or destructor — but if the template class is used as a static class, these may not be used as well.

I described a similar problem on stackoverflow [5], and was given a pretty good tip there. Thanks to that, I assembled the following universal solution:

namespace mylib
{
        extern int dummy;

        namespace
        {
                class Dummy
                {
                public:
                        inline Dummy()
                        {
                                dummy = 0;
                        }
                };

                static const Dummy dummy;
        }
}

With the int dummy variable being declared in the library code. The main (and possibly the only one) advantage of that solution is that it works with any code. The variable setting code may have side effects, thus the compiler is not allowed to optimize it out. It can however practically optimize it to a single mov instruction.

The disadvantage of that solution is that the assignment operation will be performed once for every single file including the header file. Thus, I would consider the fore-mentioned solution as a last resort, while preferring placing similar assignments in rarely-used (but always compiled) code, whenever possible.

For example, such a code may be within a rare error or exception handler. Just make sure that the compiler will not be allowed to assume that a particular branch will never be executed. For example, the following may be a bad idea:

template <type T>
void C<T>::f(int always_one = 1)
{
        if (always_one != 1)
        {
                dummy = 0;
                throw MyException();
        }

        // ...
}

Although most likely this code will work as expected, if a compiler decides to inline the function it may notice that it is always called with 1, effectively removing the whole branch. Similarly, the code should not be placed in unreachable code (because compiler may notice that) or assertions (because with NDEBUG they will be removed). And don’t forget that if f() will not be used directly at all, the whole function can be optimized out.

To sum up: if you have a safe, unlikely-called branch in your code, then it’s the best place for the assignment. If you don’t have one, then universal solution is probably the best you can get. Although it will cause unnecessary repetitions of the assignments, every other place is likely to cause even larger number of them.