[Insight-developers] Explicit Instantiation Proposal

[Brad King]

Zach,

This is the kind of discussion I was hoping to generate on the list. 
Thanks for participating.

Zachary Pincus wrote:
>> What's wrong with defining ITK_MANUAL_INSTANTIATION at the top of  the 
>> wrapper config files?
> 
> Now that the "code organization" section is up, I see that this will  
> remain possible. I was just asking if that was in fact the case. One  
> aside: right now setting ITK_MANUAL_INSTANTIATION (just for gcc-xml)  
> causes the wrappers to explode badly because of something in  
> itkVector.h and its use of the new template macros.

Please send me the error message produced.  GCC-XML should have no 
trouble swallowing the current sources whether or not 
ITK_MANUAL_INSTANTIATION is defined...as long as 
ITK_EXPLICIT_INSTANTIATION is not enabled.

> (a) preprocessor macros are a lot more unwieldy than CMake  
> macors and thus lead to a lot of the ugliness that the wiki page is  
> devoted to exposing and then hiding in yet-more preprocessor macros,  
> and (b) encoding it explicitly in a separate file that CMake can  parse 
> would allow a lot of other add-on uses for the definitions like  e.g. 
> code generators for a GUI toolkit that wants to know what sort  of 
> inputs a filter takes without having to parse horrific C++/ preprocessor 
> macro/etc. Or e.g. things like WrapITK.
> It's the old argument for separating declarative information (what  
> kinds of templates a filter takes) from procedural information (how  to 
> create explicit instances).
> 
>>>   (3) Explicit metadata about how filters should be instantiated  is  
>>> provided, which is useful for other things like wrappers.
>>
>> The instantiation names created by the macros should match the  
>> wrapper names exactly.
> 
> Not sure I follow your point here... see above about how having  
> declarative information about the filters (i.e. "metadata") in cmake  
> files is a generally useful thing.

I thought your "metadata" referred to the names to use in the wrapped 
languages for the instantiations.  These should match the explicit 
instantiation names put in the Templates namespace.  Instead you are 
talking about treating all the information currently encoded in the 
per-template instantiation macros (such as ITK_TEMPLATE_Vector) as 
metadata encoded in CMake code.  See below.

>>>   (5) The CMake macros for declaring how a filter is to be   
>>> instantiated are far easier than the preprocessor macros, because  
>>> the  latter is more powerful than the former.
>>
>> The macro-based instantiation design complements a CMake-based  
>> instantiation generator.
>>
>> Generating instantiations with CMake has been the idea all along.
> 
> Then why spend all of this time developing fairly hairy preprocessor  
> macros, and then having those macros controlled by symbols that CMake  
> may define to select which instances to instantiate, when you could  do 
> the logic more cleanly within CMake, and have CMake write out  exactly 
> the instantiation files and headers you need at configure time?

I was trying to encode the "metadata" to which you refer in a macro 
defined in the header so that the CMake code did not have to see it.

This is clearly the main point of discussion:

   - how/where should we put this information?
   - what exactly does it contain?

So, as a starting point, how is the following represented in WrapITK?

#define ITK_TEMPLATE_Foo(_, EXPORT, x, y) \
  namespace itk \
  { \
  _(1(class EXPORT Foo< ITK_TEMPLATE_1 x >)) \
  namespace Templates { typedef Foo< ITK_TEMPLATE_1 x > Foo##y; }\
  }

#define ITK_TEMPLATE_Vector(_, EXPORT, x, y) \
  namespace itk \
  { \
  _(2(class EXPORT Vector< ITK_TEMPLATE_2 x >)) \
  _(1(EXPORT std::ostream& operator<<(std::ostream&, const Vector< 
ITK_TEMPLATE_2 x >&))) \
  _(1(EXPORT std::istream& operator>>(std::istream&, Vector< 
ITK_TEMPLATE_2 x >&))) \
  namespace Templates { typedef Vector< ITK_TEMPLATE_2 x > Vector##y; }\
  }

> Otherwise, I agree that having information in two separate files is  
> more of a pain than having it in one. In the context of a global  
> reduction in C-preprocessor pain, and in pain for outside folk who  
> could make use of some explicit and easily-parsed information about  
> what sort of template parameters a given class expects, it might  still 
> be a win...

We could also put it in the .h file in the form of a comment that can be 
easily parsed by CMake code or some other tool.

>> As far as wrapper integration, a wrapper config file could now look  
>> something like
>>
>> // wrap_itkVector.cxx
>> #define ITK_MANUAL_INSTANTIATION
>> #include "Templates/itkVectorF2.h"
>> #include "Templates/itkVectorF3.h"
>> #include "Templates/itkVectorD2.h"
>> #include "Templates/itkVectorD3.h"
> 
> Shouldn't the instantiation headers just be pulled in automatically  as 
> part of the vector header? Otherwise keeping all of that stuff in  sync 
> will be a huge pain.

Yes, at least for the instantiations provided by ITK.  If the wrappers 
want more instantiations, perhaps because they are built in an outside 
project, then they will not be automatic.  Since this is all code that 
should be generated anyway it should not be a problem to keep it in sync.

> I'd be happy to talk at more length about this if anyone is  interested, 
> otherwise I'll keep quiet and let you folk go about your  work.

Let's keep going with this discussion.

-Brad