Microsoft Visual Studio Warning C4251 (DLL: template and the cascading)

http://www.unknownroad.com/rtfm/VisualStudio/warningC4251.html

 

I always try to get rid of compiler warnings. It just seems like a good thing to do. Warning-free code makes me happy. But some warnings just don't want to go away, and this is one of them. I use STL frequently, and my own templates from time to time, and every time I try to turn some code with templates into a DLL I inevitably end up with hundreds of warnings that look like this:

warning C4251: 'AClass::m_vector' : class std::vector<_Ty>' needs
to have dll-interface to be used by clients of class 'AClass'

This happens with my own non-STL template classes too:

warning C4251: 'AClass::m_variable' : class 'SomeTemplate<T>' needs
to have dll-interface to be used by clients of class 'AClass'

I'm going to explain why I think this warning happens, and what you can do to get rid of it. If you read something below that you think is wrong, please let me know. I am by no means an expert. This is just what I've figured out so far, and I'm as much making notes for myself as anything...

 

WTF?

 

I'm going to assume that you are familiar with using __declspec( dllexport ) and __declspec( dllimport ). If not, look it up in the VC++ documentation. I'll assume that you have a macro DLLImportExportMacro that exports or imports conditionally. If you don't know what I'm talking about, just create a Win32 DLL project and look at the top of the DLLName.h header that is auto-generated.

Anyway, if you mark some class AClass in a DLL as exportable with dllexport, then you have access to that class whenever you import the DLL. You also have access to various internals of that class - superclasses, protected internals (because you can subclass AClass), and anything that is used in inline functions of X (because they are compiled in your importing code, so they have to be exported).

In fact, the documentation explicitly states this in the page titled "Using dllimport and dllexport in C++ Classes" :

As a rule, everything that is accessible to the DLL's client (according to C++ access rules) should be part of the exportable interface. This includes private data members referenced in inline functions

 

This is the problem. If you have a template SomeTemplate<T>, it is not marked with dllexport because you can only export definitions, not declarations, and a template is not a definition. It's code is only created when you create an instantiation. So when you have this:

class DLLImportExportMacro AClass
{
public:
   SomeTemplate<int> GetVariable() { return y; }
protected:
   SomeTemplate<int> y;
};

Then SomeTemplate<int> is an instantiation of SomeTemplate<T> that is accesible to clients of AClass but is not exported!

Now, if AClass was not exported and you tried to use it in some importing code, you would get link errors. And if you replace SomeTemplate<int> with a non-template non-exported class, and try to call the GetVariable() function in some importing code, you will again get link errors. But calling GetVariable() as defined above in importing code does not produce any errors!. It works just fine!

I think this is a case where something works even though it shouldn't. SomeTemplate<int> is not exported. So the warning is not incorrect. But in calling code, whenever you might use SomeTemplate<int>, the compiler is going to automatically instantiate SomeTemplate<T>, creating a local version of SomeTemplate<int>. They are the same code, so all the same symbols are defined, and there are no link errors. I guess we could call this "implicit exporting" - the header for SomeTemplate<T> is necessarily exported, and the template instantiation mechanism implicitly imports it by re-generating the code locally.

I suppose it's possible that you might have compiled the DLL containing AClass with different flags or something. In that case you might be able to get a link error. I haven't tried this...

 

Workaround 1 - Disable the Warning

 

Ok, so this warning is a nuisance and you want it to go away. One option is to simply disable it. Just put the following code at the bottom of some header that is included before any of the DLL headers (stdafx.h works well for me....):

#pragma warning( disable: 4251 )

This will get rid of your warnings. But in the previous section I noted that there are cases where this warning does tell you something important (when SomeTemplate<T> is replaced by a non-exported non-template class). In that case you will get link errors if you try to access this class from the importing code. So the warning is helpful there.

Of course, it does mean you have to scour the 4251 warnings to see if there is any non-template stuff in there. If you are the only one using your DLL, you'll find out about the link errors soon enough. So maybe disabling is the best option...

I'm going to explain another workaround, but I'll warn you right now that it doesn't work all the time, particularly for STL.

 

Workaround 2 - Explicit Template Instantiation

 

Lets look at this code again:

class DLLImportExportMacro AClass

{
public:
   SomeTemplate<int> GetVariable() { return y; }
protected:
   SomeTemplate<int> y;
};

Warning C4251 pops up because SomeTemplate<int> is not exported. Now ideally we would export SomeTemplate<T> and all it's instantiations would be exported, but that only works in fantasy land. In reality, SomeTemplate<T> is a declaration only, and a declaration cannot be exported because there is no actual code to back it up. However, SomeTemplate<int> is a definition, not a declaration, so we can export it. We simply have to mark the instantiation with DLLImportExportMacro. Sounds easy, but since the instantiation is automatically done by the header how the hell are you supposed to mark it with a macro?

Well, you have to beat the compiler to the punch and instantiate the template yourself. This is called explicit instantiation and is simple to do. Here is what you would do for the above example:

class DLLImportExportMacro AClass

{
public:
   SomeTemplate<int> GetVariable() { return y; }
protected:
   template class DLLImportExportMacro SomeTemplate<int>;
   SomeTemplate<int> y;
};

That "template class ..." bit is the explicit instantiation, and we throw your DLL import/export macro in there so that the explicit instantiation is exported. This will shut up the compiler and clear up the C4251 warning. But note that it has no actual effect on the running of your code - it will have worked before. This just avoids the warning.

 

Workaround 2 For STL

 

So far I've been working with your hypothetical template class SomeTemplate<T>. Now let's consider the case where SomeTemplate<T> is in fact std::vector<T>:

class DLLImportExportMacro AClass

{
public:
   std::vector<int> GetVariable() { return y; }
protected:
   template class DLLImportExportMacro std::vector<int>;
   std::vector<int> y;
};

This seems easy, right? But it doesn't work. Now you are going to get something like this:

warning C4251: 'std::_Vector_val<_Ty,_Alloc>::_Alval' : 
class std::allocator<_Ty>' needs to have dll-interface to 
be used by clients of class 'std::_Vector_val<_Ty,_Alloc>'

Which will be frustrating. This is because while we all use "std::vector<T>", the actual class definition has a default template parameter defining the allocator, "std::vector<T, std::allocator<T> >". This whole exporting thing cascades to variables inside the templates you want to export. So you have to export the allocator too, and export the full vector template definition:

class DLLImportExportMacro AClass

{
public:
   std::vector<int> GetVariable() { return y; }
protected:
   template class DLLImportExportMacro std::allocator<int>
   template class DLLImportExportMacro std::vector<int, std::allocator<int> >;
   std::vector<int> y;
};

If you do this, then the C4251 warning will go away. Hurray! Again, no effect on the actual execution of your code. Just avoiding a warning.

Note that this cascading can happen for your own templates too. And there is one case where it is important - when your template SomeTemplate<T> contains a non-template class object that is not exported. In this case, you have to export that class or you will get link errors.

 

Workaround 2 for Other STL Classes

 

We saw above that we also had to export the allocator for std::vector to get the warnings to stop. How about for other STL classes? You had to ask. I've only needed to do this for std::set and std::map, so those are the two I will show. Understand that internally these classes are quite a bit more complicated than std::vector. I'm going to present all 3 (vector, set, and map) as macros that you can cut and paste. Here goes:

Note: In these macros you need to replace 'dllmacro' with whatever your import/export macro is

#define EXPORT_STL_VECTOR( dllmacro, vectype ) \
  template class dllmacro std::allocator< vectype >; \
  template class dllmacro std::vector<vectype, std::allocator< vectype > >;


#define EXPORT_STL_SET( dllmacro, settype ) \
  template class dllmacro std::allocator< settype >; \
  template struct dllmacro std::less< settype >; \
  template class dllmacro std::allocator< \
    std::_Tree_nod<std::_Tset_traits<settype,std::less<settype>, \
    std::allocator<settype>,false> > >; \
  template class dllmacro std::allocator<  \
    std::_Tree_ptr<std::_Tset_traits<settype,std::less<settype>, \
    std::allocator<settype>,false> > >; \
  template class dllmacro std::_Tree_ptr< \
    std::_Tset_traits<settype,std::less<settype>, \
    std::allocator<settype>,false> >; \
  template class dllmacro std::_Tree_nod< \
    std::_Tset_traits<settype,std::less<settype>, \
    std::allocator<settype>,false> >; \    
  template class dllmacro std::_Tree_val< \
    std::_Tset_traits<settype,std::less<settype>, \
    std::allocator<settype>,false> >; \    
  template class dllmacro std::set< settype, std::less< settype >, \
    std::allocator< settype > >; 


#define EXPORT_STL_MAP( dllmacro, mapkey, mapvalue ) \
  template struct dllmacro std::pair< mapkey,mapvalue >; \
  template class dllmacro std::allocator< \
    std::pair<const mapkey,mapvalue> >; \
  template struct dllmacro std::less< mapkey >; \
  template class dllmacro std::allocator< \
    std::_Tree_ptr<std::_Tmap_traits<mapkey,mapvalue,std::less<mapkey>, \
    std::allocator<std::pair<const mapkey,mapvalue> >,false> > >; \
  template class dllmacro std::allocator< \
    std::_Tree_nod<std::_Tmap_traits<mapkey,mapvalue,std::less<mapkey>, \
    std::allocator<std::pair<const mapkey,mapvalue> >,false> > >; \
  template class dllmacro std::_Tree_nod< \
    std::_Tmap_traits<mapkey,mapvalue,std::less<mapkey>, \
    std::allocator<std::pair<const mapkey,mapvalue> >,false> >; \
  template class dllmacro std::_Tree_ptr< \
    std::_Tmap_traits<mapkey,mapvalue,std::less<mapkey>, \
    std::allocator<std::pair<const mapkey,mapvalue> >,false> >; \
  template class dllmacro std::_Tree_val< \
    std::_Tmap_traits<mapkey,mapvalue,std::less<mapkey>, \
    std::allocator<std::pair<const mapkey,mapvalue> >,false> >; \
  template class dllmacro std::map< \
    mapkey, mapvalue, std::less< mapkey >, \
    std::allocator<std::pair<const mapkey,mapvalue> > >;
          

Yea. Ugly. Soooo ugly. All this just to get rid of some warnings. And I've got bad news....

 

Workaround 2 can cause link errors...

 

That's right. Fixing warning C4251 for templates can cause multiply-defined symbol errors. Say you have some DLL with an exported class containing a std::vector<int> that you have explicitly instantiated and exported as shown above. Your C4251 warnings are fixed. Nice! But then you want to use another DLL that has an exported class containing a std::vector<int> with the same explicit-instantiation workaround. Trouble...

When you try to link to both DLLs at the same time, you will get multiply-defined symbol errors! Both DLLs contain a specific class called std::vector<int>. They each have a copy of the symbols generated during template instantiation. The linker has no idea that the symbols are the same because the underlying code is the same, because it's in the compiled DLLs that it doesn't have access to. So it spits out link errors....

This is monumentally frustrating, in my opinion. As far as I can see the only real option here is to disable the warning and ignore it. You simply cannot use std::vector for simple types in classes exported from DLLs without at least generating warnings.

One thing that should work but doesn't is to make your vector private and not use it in inline functions. According to the documentation snippet shown above, this should be ok. It is not accesible to clients of the DLL. But the warning still comes up.

Another very unappealing option is to create a DLL where you explicitly instantiate all the STL classes you want ot use (vector, map, and so on) and wrap each of them, and then use the wrappers everywhere in your DLL interfaces. The wrappers are easy to write, just subclass the type you want (ie IntVector : public std::vector<int>) and do the explicit instantiation trick above the class definition. But you'll have to write constructors too, and you'll have to do this for each pair of stl container / datatype you want to use in your DLL interfaces. Seems like a lot of work to me....

 

Microsoft to the Rescue! (....well....sort of....)

 

Microsoft has (recently?) added a knowledge base article about this problem. Here is a link to the article:

How To Exporting STL Components Inside & Outside of a Class

(Yes. That is really the title. You would think someone checked at least the titles for grammar...)

Anyway, the gist of this article is that you cannot export anything except std::vector. I have not studied it extensively. It might deal with the link errors I mentioned before - but only for vectors. Yes, only for vectors. This KB article says that all other classes contain internal classes which cannot be exported. Which, I guess, means that those macros above only hide the warnings, but don't actually change the export behavior. Which might explain the link errors I have seen (they were all for vector!). Anyway, I'm still just hiding the warning with a pragma...

 

Conclusion

 

Disable the warning? You can do it locally and cleanly using pragma warning (push : XXXX) and (pop : XXXX) around your disable pragma, check the docs for pragma warning. You shouldn't just blindly disable the warning for anyone else who includes your header, because maybe they want that warning turned on. And if you are shipping a DLL to someone else, you probably want to be certain that all the non-template classes you want to export are marked as such. In this case disabling the warning might not be such a good idea...

I have no idea what the "right" behavior is here. It would be nice if we could say that the link error is wrong, but it's not. The linker has two different DLLs with the same symbols. It would be space madness for the linker to assume that it was the same code.

Warning C4251 isn't really wrong either. Your template instantiation is not exported. I suppose if you compiled the DLL with VC6 and the calling code with VC7 you might get some differences in the template instantiation name mangling or something that would cause link errors. Or even worse, the name mangling would be the same but the instantiation memory alignment would be slightly different or something. You could get crashes in that case.

Note: It seems that the above situation has occurred, between Visual Studio 7 and 8. Loren Meck writes " the predicted crashes do indeed happen when linking VC7 executables that use std::vector with VC8 executables that also use std::vector ". So, that's bad....very, very bad....

So the warning does have a purpose. But even with the explicit instantiation, I'm not certain the calling code is actually using it. This just seems to be one of the many C++ template inconsistencies that we just have to live with. Or switch to C#, I guess....