[Insight-developers] Explicit Instantiation Proposal

[Brad King]

Zachary Pincus wrote:
> (1) Are there plans for limited CMake control of what gets  
> instantiated? E.g. defining some symbols INSTANTIATE_INT,  
> INSTANTIATE_2D, or whatever, that the generic macros will key into  with 
> #ifdefs, etc? Or will filter developers just decide on their own  which 
> filters and which types ought to be explicitly instantiated?

I like the WrapITK approach of allowing the set of instantiations to be 
configured.  However another goal is to be able to build the entire ITK 
testing tree using mostly explicit instantiations so that it builds more 
quickly.

> (2) A request: it would be really nice for WrapITK if there was a way  
> to exclude the .txx files from being parsed by gcc-xml. Specifically,  a 
> preprocessor symbol that *only* serves to be the gatekeeper to the  txx 
> files. Right now, it's ITK_MANUAL_INSTANTIATION (except for with  
> itkVector, which I don't fully grok). It would be great if through  all 
> of this, there remained one symbol that does nothing but  determine 
> whether the .txx files are #included.

What's wrong with defining ITK_MANUAL_INSTANTIATION at the top of the 
wrapper config files?

> (3) There is another approach to the explicit template instantiation  
> process that I have been thinking about. Now, I'm not sure it is a  good 
> idea, and it may even be overtly bad, but here goes.
 >
> In WrapITK, we have a bunch of little CMake files, one for each  filter 
> more or less, that in a fairly clear syntax describe the  template types 
> that that filter may be instantiated with. Then when  we read through 
> these files in the CMake stage, we take the union of  the possible 
> templates with the user-selected wrapping types, and  generate CableSwig 
> input files.
> 
> There's no reason that a similar process couldn't do what's needed  for 
> explicit template instantiation. CMake would read a file  describing the 
> filter and then write a .cxx file containing the  instantiations, and 
> write another header or something that has the  'extern' or 
> 'do_not_instantiate' lines. The cxx and header files  could be written 
> for each filter, or omnibus ones could be written  for each library.

Something along these lines should definately be done.  This section can 
be filled in as the design is created:

http://www.itk.org/Wiki/Proposals:Explicit_Instantiation#Generating_Instantiations

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

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

How is this finer-grained?

>   (2) Less tricky macros

Possibly, but the information about what to instantiate for a given 
template has to be encoded somewhere.

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

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

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"

#ifdef CABLE_CONFIGURATION
#include "itkCSwigMacros.h"
namespace _cable_
{
   const char* const group = ITK_WRAP_GROUP(itkVector);
   namespace wrappers
   {
   typedef itk::Templates::VectorF2::Self VectorF2;
   typedef itk::Templates::VectorF3::Self VectorF3;
   typedef itk::Templates::VectorD2::Self VectorD2;
   typedef itk::Templates::VectorD3::Self VectorD3;
   }
}
#endif

We could also replace the

#define ITK_MANUAL_INSTANTIATION

with

#define ITK_WRAPPER_CXX 1

to be more similar to the instantiation files.

-Brad