[Insight-developers] Explicit Instantiation Proposal

[Zachary Pincus]

> 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.

>> The bottom of any header could then look thus:
>> #ifdef EXPLICIT_INSTANCES
>> #include itkFooInstances.h // auto-generated by CMake
>> // (or #include itkCommonInstances.h if the omnibus approach was  
>> taken)
>> #endif
>> #include itkFoo.txx
>> And then to make the instantiations for ITKCommon, just compile  
>> the  one or multiple cxx files (ITKCommonInstances.cxx or   
>> itkFooInstances.cxx/itkBarInstances.cxx/itk...) that CMake has   
>> generated.
>
> Read the section of the Wiki page about Organizing Source Files to  
> see why there has to be one instantiation per object file.

OK.

As to below, what I was doing was making the case for putting more of  
the logic in CMake and less of the logic in preprocessor macros  
because I find the former to be more maintainable than the latter. It  
was just a thought.

>> Advantages of this approach:
>>   (1) Finer-grained control of what gets instantiated, and how
>
> How is this finer-grained?

Because it allows tighter interaction between what the user might  
select to instantiate in CMake with the actual process of creating  
the instantiations. Doing this all via preprocessor symbols could get  
ugly quickly. Doing it via explicit logic in cmake (which is what the  
WrapITK wrappers do) gave us a lot of flexibility that we have made  
good use of.

>
>>   (2) Less tricky macros
>
> Possibly, but the information about what to instantiate for a given  
> template has to be encoded somewhere.

Right. But (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.

>
>>   (4) A glance at the list of filters with corresponding cmake   
>> metadata files indicates which ones have been so described.
>
> This will be true if we use CMake to generate the instantiation  
> sources no matter how they are implemented.
>
>>   (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?


> Encoding the declarations used in the instantiation of a particular  
> template in a macro inside the header file keeps everything about  
> the template in one place.

It also keeps that very useful information inaccessible except in the  
narrow context of explicit template instantiation, when it could  
instead be a general resource for people who want to do complex stuff  
with the ITK filters. This and this alone is my main point: by  
building an ever-so-slightly more generic system for representing  
information about templates, and then using that system to make the  
template instantiations, you have also built a system that other  
people can use for other really useful things.


>   Then the input to the instantiation generator need only concern  
> itself with the template arguments and instantiation names.  If  
> something is added to a template that requires more instantiation  
> lines only the macro needs to be changed instead of a bunch of  
> CMake files that may not even be in the same CVS repository.

The bit about being in another CVS is something of a straw man.  
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...

>
> 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.


Anyhow, I'm not trying to be combative or anything. I just wanted to  
point out that this could be a nice opportunity to build a general  
system for describing the ITK templates. And that using such a  
general system to then drive the explicit instantiation (as well as  
wrapping, or other nice things) could accrue several advantages over  
doing it all within the preprocessor.

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.

Zach