In the C++ language, there are not many features who are as powerful as templates. But their strength is also contributing to the complexity of templates.

With standard classes and structs, you can hide the implementation of the methods within the class, and you can put those in a separate compilation units (cpp files).

With templates, there is a whole other story. When the compiler sees a template (class and method), it must know the internals of that particular method. This is because templates doesn’t really exist until they are used, and with varying template parameters, the classes and structs are generated, and is in reality completely separate classes for different parameters.

Here is one quirk, circular dependencies with templated classes and classes with templated methods. All code in the post (and build scripts) are available at https://github.com/Studiofreya/code-samples/tree/master/circular-templates.

In this particular case, Visual Studio is sort of stupid. It deliberately accepts code, which it really shouldn’t accept. This isn’t really a problem if you only target the Microsoft stack and environment. If you plan to deploy to other platforms, it’ll be a problem. The best advice is to get up both build systems early in the development, so any problems are caught early.

But on with the problem. Consider the following file.

// This file only compiles in Visual Studio 2010 and newer

template
class Message
{
    public:
        typedef T       type;

        static const int MsgId   = 0;

        explicit Message( const T & t )
            : data(t)
        {
        }

        type        data;
};

typedef Message    MsgInt;
typedef Message   MsgLong;
typedef Message  MsgFloat;
typedef Message MsgDouble;

class MessageHandler
{
    public:

        template
        void setHandler( const T & msghandler )
        {
            /* do stuff */
            auto id = MSG::MsgId; // Make sure this is a message type
        }
};

// Forward declaration of classes
class Component;
class Entity;

class Component
{
    public:

        template
        void setEntityHandler( Entity & entity )
        {
            auto handleMsg = [&] ( const MSG & msg )
            {
                /* do stuff */
            };

            entity.m_MessageHandler.setHandler( handleMsg );
        }

        MessageHandler  m_MessageHandler;

};

class Entity
{
    public:

        template
        void setComponentHandler( Component & component )
        {
            auto handleMsg = [&] ( const MSG & msg )
            {
                /* do stuff */
            };

            component.m_MessageHandler.setHandler( handleMsg );
        }

        MessageHandler  m_MessageHandler;
};

int main()
{
    Component c;
    Entity e;

    e.setComponentHandler(c);

	return 0;
}

The problem is in this line entity.m_MessageHandler.setHandler( handleMsg ); in the Component class. It uses an undefined class which has been forward declared. Visual Studio is trying to be smart and it can see forwards there is an implementation (definition) of the Entity class further down below. GCC (g++) is not trying to be smart, and thus will the code above fail to compile with g++.

Here is the error with g++.

g++-4.8.1 -std=c++11 circular-templates.cpp -o circdep
circular-templates.cpp: In member function ‘void Component::setEntityHandler(Entity&)’:
circular-templates.cpp:55:19: error: invalid use of incomplete type ‘class Entity’
             entity.m_MessageHandler.setHandler( handleMsg );
                   ^
circular-templates.cpp:41:7: error: forward declaration of ‘class Entity’
 class Entity;
       ^
circular-templates.cpp:55:51: error: expected primary-expression before ‘>’ token
             entity.m_MessageHandler.setHandler( handleMsg );
                                                   ^

Here is the fixed code where it will compile in both MSVC and g++.

// This file compiles in both Visual Studio 2010 (and newer) and G++ with C++11.

template
class Message
{
    public:
        typedef T       type;

        static const int MsgId   = 0;

        explicit Message( const T & t )
            : data(t)
        {
        }

        type        data;
};

typedef Message    MsgInt;
typedef Message   MsgLong;
typedef Message  MsgFloat;
typedef Message MsgDouble;

class MessageHandler
{
    public:

        template
        void setHandler( const T & msghandler )
        {
            /* do stuff */
            auto id = MSG::MsgId; // Make sure this is a message type
        }
};

// Forward declaration of classes
class Component;
class Entity;

class Component
{
    public:

        template
        void setEntityHandler( Entity & entity );

        MessageHandler  m_MessageHandler;

};

class Entity
{
    public:

        template
        void setComponentHandler( Component & component );

        MessageHandler  m_MessageHandler;
};

// Implementation of circular dependencies
template
void Component::setEntityHandler( Entity & entity )
{
    auto handleMsg = [&] ( const MSG & msg )
    {
        /* do stuff */
    };

    entity.m_MessageHandler.setHandler( handleMsg );
}

template
void Entity::setComponentHandler( Component & component )
{
    auto handleMsg = [&] ( const MSG & msg )
    {
        /* do stuff */
    };

    component.m_MessageHandler.setHandler( handleMsg );
}

// Main
int main()
{
    Component c;
    Entity e;

    e.setComponentHandler(c);

	return 0;
}

This file will compile in both MSVC and G++, and with MSVC it’ll produce identical assembly code for both files.

The clue to solving this problem is to declare both classes before providing the definitions (implementations). It’s not possible to split the declaration and definition into separate files, but you can structure them as if they were in separate files. Here both Entity and Component are declared before any implementation code.

All code in the post (and build scripts) are available at https://github.com/Studiofreya/code-samples/tree/master/circular-templates.