DictSelectionReader.h File Reference

#include "clang/AST/RecursiveASTVisitor.h"
#include <llvm/ADT/StringMap.h>
#include <set>
#include <unordered_set>
#include <string>
#include <unordered_map>

Include dependency graph for DictSelectionReader.h:

This graph shows which files directly or indirectly include this file:

Classes
class	ROOT::Internal::DictSelectionReader
struct	ROOT::Internal::DictSelectionReader::TemplateInfo

Namespaces
namespace	clang
namespace	ROOT
	tbb::task_arena is an alias of tbb::interface7::task_arena, which doesn't allow to forward declare tbb::task_arena without forward declaring tbb::interface7
namespace	ROOT::Internal
namespace	ROOT::TMetaUtils

Detailed Description

Select classes and assign properties using C++ syntax.

Author

Danilo Piparo

Date

January 2014

When generating dictionary information for a class, one sometimes wants to specify additional information beyond the class definition itself, for example, to specify that certain members are to be treated as transient by the persistency system. This can be done by associating a dictionary selection class with the class for which dictionary information is being generated. The contents of this selection class encode the additional information. Below, we first discuss how to associate a selection class with your class; then we list the current Set of information which may appear inside the selection class.

The simplest case is for the case of a non-template class C. By default, the Name of the selection class is then ROOT::Meta::Selection::C. If you have such a class, it will be found automatically. If C is in a namespace, NS::C, then the selection class should be in the same namespace: ROOT::Meta::Selection::NS::C.

Examples:

The DictSelectionReader is used to create selection rules starting from C++ the constructs of the ROOT::Meta::Selection namespace. All rules are matching by name. A brief description of the operations that lead to class selection:

1. If a class declaration is present in the selection namespace, a class with the same name is selected outside the selection namespace.
2. If a template class declaration and a template instantiation is present in the selection namespace, all the instances of the template are selected outside the namespace.

For example:

[...]
class classVanilla{};
template <class A> class classTemplateVanilla {};
classTemplateVanilla<char> t0;
namespace ROOT {
   namespace Meta {
      namespace Selection {
         class classVanilla {};
         template <typename A> class classTemplateVanilla {};
         classTemplateVanilla<char> st0;
      }
   }
}

would create two selection rules to select classVanilla and classTemplateVanilla<char>.

A brief description of the properties that can be assigned to classes with the ROOT::Meta::Selection::ClassAttributes class.

1. kNonSplittable : Makes the class non splittable

The class properties can be assigned via a traits mechanism. For example:

[...]
class classWithAttributes {};
namespace ROOT {
   namespace Meta {
      namespace Selection {
         class classWithAttributes : ClassAttributes <kNonSplittable> {};
      }
   }
}

would create a selection rule which selects class classWithAttributes and assignes to it the property described by kNonSplittable. Multiple properties can be assigned to a single class with this syntax:

[...]
namespace ROOT {
   namespace Meta {
      namespace Selection {
         class classWithAttributes :
            ClassAttributes <kProperty1 + kProperty2 + ... + kPropertyN> {};
      }
   }
}

The ROOT::Meta::Selection syntax allows to alter the number of template parameters of a certain template class within the ROOT type system, TClass. Technically it allows to alter the way in which the "normalized name" (in other words, the "ROOT name") of the class is created. The key is the usage of the KeepFirstTemplateArguments traits class. It is possible to select the maximum number of template arguments considered if not different from the default. A concrete example can be more clear than a long explaination in this case:

[...]
template <class T, class U = int, int V = 3> class A {...};
template <class T, class Alloc = myAllocator<T> > class myVector {...};
A<char> a1;
A<char, float> a2;
myVector<float> v1;
myVector<A<char>> v2;
 
namespace ROOT {
   namespace Meta {
      namespace Selection {
         template <class T, class U = int, int V = 3> class A
           : KeepFirstTemplateArguments<1> {};
         A<double> a;
         template <class T, class Alloc = myAllocator<T> > class myVector
           : KeepFirstTemplateArguments<1> {};
         myVector<double> vd;
      }
   }
}

Consistently with what described above, all the instances of A and myvector will be selected. In addition, only the first template parameter will be kept. In absence of any KeepFirstTemplateArguments trait, the normalization would be:

• A<char> → A<char,float,3>
• A<char,float> → A<char,int,3>
• myVector<float> → myVector<A<char,int,3>,myAllocator<A<char,int,3>>>
• myVector<A<char>> → myVector<float,myAllocator<float>>

Now, deciding to keep just one argument (KeepFirstTemplateArguments<1>):

• A<char> → A<char,float>
• A<char,float> → A<char>
• myVector<float> → myVector<A<char>,myAllocator<A<char>>>
• myVector<A<char>> → myVector<float,myAllocator<float>>

And deciding to keep two arguments (KeepFirstTemplateArguments<2>):

• A<char> → A<char,float>
• A<char,float> → A<char,int>
• myVector<float> → myVector<A<char,int>,myAllocator<A<char,int>>>
• myVector<A<char>> → myVector<float,myAllocator<float>>

A brief description of the properties that can be assigned to data members with the ROOT::Meta::Selection MemberAttributes class:

1. kTransient : the data member is transient, not persistified by the ROOT I/O.
2. kAutoSelected : the type of the data member is selected without the need of specifying its class explicitely.

For example:

[...]
class classTransientMember {
 private:
   int transientMember;
};
class classAutoselected {};
class classTestAutoselect {
 private:
   classAutoselected autoselected;
};
 
namespace ROOT {
   namespace Meta {
      namespace Selection {
         class classTestAutoselect {
            MemberAttributes<kAutoSelected> autoselected;
         };
         class classTransientMember {
            MemberAttributes<kTransient> transientMember;
         };
      }
   }
}

would lead to the creation of selection rules for classTransientMember specifying that transientMember is transient, classTestAutoselect and classAutoselected.

Another trait class present in the ROOT::Meta::Selection is SelectNoInstance. If a template in the selection namespace inherits from this class, none of its instantiations will be automatically selected but all of the properties specified otherwise, like transient members or number of template arguments to keep, will be transmitted to all of the instantiations selected by other means. For example

[...]
template< class T, class BASE >
class MyDataVector : KeepFirstTemplateArguments< 1 >, SelectNoInstance {
    MemberAttributes< kTransient + kAutoSelected > m_isMostDerived;
    MemberAttributes< kNonSplittable + kAutoSelected > m_isNonSplit;
};
[...]

Definition in file DictSelectionReader.h.