doc/charm++/templates.tex

   1
   2 \index{templates}
   3
   4 % Intro
   5
   6 Templates are a mechanism provided by the \CC language to parametrize code over
   7 various types and constants with compile-time code specialization for each
   8 instance. \charmpp allows developers to implement various entities using \CC
   9 templates to gain their advantages in abstraction, flexibility, and
  10 performance. Because the \charmpp runtime system requires some generated code
  11 for each entity type that is used in a program, template entities must each
  12 have a declaration in a .ci file, a definition in a \CC header, and
  13 declarations of their instantiations in one or more .ci files.
  14
  15 % Mechanics
  16 %% Declaration
  17
  18 The first step to implementing a templated \charmpp entity is declaring it as
  19 such in a .ci file. This declaration takes the same form as any \CC template:
  20 the {\tt template} keyword, a list of template parameters surrounded by angle
  21 brackets, and the normal declaration of the entity with possible reference to
  22 the template parameters. The \charmpp interface translator will generate
  23 corresponding templated code for the entity, similar to what it would generate
  24 for a non-templated entity of the same kind. Differences in how one uses this
  25 generated code are described below.
  26
  27 A message template might be declared as follows:
  28 \begin{alltt}
  29 module A \{
  30   template <class DType, int N=3>
  31   message TMessage;
  32 \};
  33 \end{alltt}
  34 Note that default template parameters are supported.
  35
  36 If one wished to include variable-length arrays in a message template, those
  37 can be accomodated as well:
  38 \begin{alltt}
  39 module B \{
  40   template <class DType>
  41   message TVarMessage \{
  42     DType payload[];
  43   \};
  44 \};
  45 \end{alltt}
  46
  47 Similarly, chare class templates (for various kinds of chares) would be
  48 written:
  49 \begin{alltt}
  50 module C \{
  51   template <typename T>
  52   chare TChare \{
  53     entry TChare();
  54     entry void doStuff(T t);
  55   \};
  56
  57   template <typename U>
  58   group TGroup \{
  59     entry TGroup();
  60     entry void doSomethingElse(U u, int n);
  61   \};
  62
  63   template <typename V, int s>
  64   array [2D] TArray \{
  65     entry TArray(V v);
  66   \};
  67
  68   template <typename W>
  69   nodegroup TNodeGroup \{
  70     entry TNodeGroup();
  71     entry void doAnotherThing(W w);
  72   \};
  73 \};
  74 \end{alltt}
  75
  76 Entry method templates are declared like so:
  77 \begin{alltt}
  78 module D \{
  79     array [1D] libArray \{
  80         entry libArray(int _dataSize);
  81         template <typename T>
  82         entry void doSomething(T t, CkCallback redCB);
  83     \};
  84 \};
  85 \end{alltt}
  86
  87 %% Definition
  88
  89 The definition of templated \charmpp entities works almost identically to the
  90 definition of non-template entities, with the addition of the expected template
  91 signature:
  92 \begin{alltt}
  93 // A.h
  94 #include ``A.decl.h''
  95
  96 template <class DType, int N=3>
  97 struct TMessage : public CMessage_TMessage<DType, N> \{
  98   DType d[N];
  99 \};
 100
 101 #define CK_TEMPLATES_ONLY
 102 #include ``A.def.h''
 103 #undef CK_TEMPLATES_ONLY
 104 \end{alltt}
 105 The distinguishing change is the additional requirement to include parts of the
 106 generated .def.h file that relate to the templates being defined. This exposes
 107 the generated code that provides registration and other supporting routines to
 108 client code that will need to instantiate it. As with \CC template code in
 109 general, the entire definition of the templated entity must be visible to the
 110 code that eventually references it to allow instantiation. In circumstances
 111 where {\tt module A} contains only template code, some source file including
 112 {\tt A.def.h} without the template macro will still have to be compiled and
 113 linked to incorporate module-level generated code.
 114
 115 %% Instantiation
 116
 117 Code that references particular templated entities needs to ask the interface
 118 translator to instantiate registration and delivery code for those
 119 entities. This is accomplished by a declaration in a {\tt .ci} file that names
 120 the entity and the actual template arguments for which an instantiation is
 121 desired.
 122
 123 For the message and chare templates described above, a few instantiations might
 124 look like
 125 \begin{alltt}
 126 module D \{
 127   extern module A;
 128   message TMessage<float, 7>;
 129   message TMessage<double>;
 130   message TMessage<int, 1>;
 131
 132   extern module C;
 133   array [2D] TArray<std::string, 4>;
 134   group TGroup<char>;
 135 \};
 136 \end{alltt}
 137
 138 Instantiations of entry method templates are slightly more complex, because
 139 they must specify the chare class containing them. The template arguments are
 140 also specified directly in the method's parameters, rather than as distinct
 141 template arguments.
 142 \begin{alltt}
 143 module E \{
 144   extern module D;
 145
 146   // syntax: extern entry void chareClassName templateEntryMethodName(list, of, actual, arguments);
 147   extern entry void libArray doSomething(int&, CkCallback redCB);
 148 \};
 149 \end{alltt}
 150
 151 To enable generic programming using \charmpp entities, we define a number of type trait
 152 utilities. These can be used to determine at compile-time if a type is a certain kind
 153 of \charmpp type:
 154 \begin{alltt}
 155 #include "charm++_type_traits.h"
 156
 157 // Is T a chare array proxy?
 158 using result = charmxx::is_array_proxy<T>;
 159
 160 // Is T a group proxy?
 161 using result = charmxx::is_group_proxy<T>;
 162
 163 // Is T a node group proxy?
 164 using result = charmxx::is_node_group_proxy<T>;
 165
 166 // Is T a chare proxy?
 167 using result = charmxx::is_chare_proxy<T>;
 168
 169 // Is T a bound array?
 170 using result = charmxx::is_bound_array<T>;
 171
 172 // Does T have a PUP routine defined for it?
 173 using result = charmxx::is_pupable<T>;
 174 \end{alltt}
 175