]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Explain a little better what is going on.
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Fri, 20 Jan 2006 16:50:23 +0000 (16:50 +0000)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Fri, 20 Jan 2006 16:50:23 +0000 (16:50 +0000)
git-svn-id: https://svn.dealii.org/trunk@12112 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/doc/doxygen/headers/instantiations.h

index 8a19b9373230e937a6bd882413fa2b3b0094aece..836cb2f7e3db0bb30a0aeec6b05d28d92d61005e 100644 (file)
@@ -1,26 +1,18 @@
 /**
  * @page Instantiations Template instantiations
  *
- * <h4>Contents</h4>
- * <ol>
- * <li> @subpage Inst1 "Few"
- * <li> @subpage Inst2 "Some"
- * <li> @subpage Inst3 "Many"
- * </li>
- *
- * The instantiation of complex function templates costs a lot of
- * compile time and blows up the size of the resulting object
- * files. Therefore, declaration and implementation of these functions
- * should be split and the implementation should be read by the
- * compiler only when really necessary. We achieve compile time
- * efficiency by implementing the following concept:
- *
- * Template classes in <tt>deal.II</tt> are split into three
- * categories, depending on the number of probable different
- * instantiations. Accordingly, the function definitions are in
- * different places.
- *
- * @section Inst1 Few instantiations
+ * Instantiation of complex class and function templates is expensive both in
+ * terms of compile time and disk space. Therefore, we try to separate
+ * declaration and implementation of templates as far as possible, and make
+ * sure that implementations are read by the compiler only when 
+ * necessary.
+ *
+ * Template classes in <tt>deal.II</tt> can be grouped into three categories,
+ * depending on the number of probable different instantiations. These three
+ * groups are discussed in the following.
+ * 
+ *
+ * @section Inst1 Known and fixed number of instantiations
  *
  * These are the classes having template parameters with very
  * predictable values. The typical prototype is
  * template <int dim> class Function;
  * @endcode
  *
- * Here, we have a small number of instantiations (dim = 1,2,3)
- * known at the time of design of the library. Therefore, member
- * functions of this class are defined in a <tt>.cc</tt> file in the
- * source directory and all instantiations are in the source file.
+ * Here, we have a small number of instantiations (<code>dim = 1,2,3</code>)
+ * known at the time of design of the library. Therefore, member functions of
+ * this class are defined in a <tt>.cc</tt> file in the source directory and
+ * we instantiate the template for these known values explicitly in the source
+ * file.
  *
- * This means that it is in fact not the template being part of the
- * library, but its instantiation; in the case of triangulation
- * objects of the <tt>deal.II</tt> library, implementations may be
- * completely different indeed. There, we even put instantiations for
- * different template parameters into different libraries.
+ * From an application viewpoint, all you actually get to see then is the
+ * declaration of the template. Actual instantiations of member functions
+ * happens inside the library and is done when you compile the library, not
+ * when you compile your application code.
  *
- * For these classes, adding instantiations for new parameters
- * involves changing the library.
+ * For these classes, adding instantiations for new parameters involves
+ * changing the library. However, this is rarely needed, of course, unless you
+ * are not content with computing only in 1d, 2d, or 3d.
+ * 
  *
  * @subsection Inst1a Available instances
  *
  * If the template parameter is <tt>dim</tt>, the available instances
  * are for <tt>dim=1,2,3</tt>, if there is no other information.
  *
- * For other classes, the list of available instances is often listed
- * in the line
- @verbatim
- Template Instantiations: few  (<p1> <p2>)
- @endverbatim
+ * There are other cases of classes (not depending on the spatial dimension)
+ * for which only a certain, small number of template arguments is supported
+ * and explicit instantiations are provided in the library. In particular,
+ * this includes all the linear algebra classes that are templatized on the
+ * type of the scalar underlying stored values: we only support
+ * <code>double</code>, <code>float</code>, and in some cases <code>long
+ * double</code>.
+ * 
  *
  * @section Inst2 Some instantiations
  *
- * These are class templates usually having a small number of
- * instantiations, but additional instantiations may be
- * necessary. Therefore, a set of instantiations for standard
- * parameters is provided precompiled in the libraries.
- *
- * Generic example of such a class is
- * @code
- * template<typename number> class Polynomials::Polynomial<number>;
- * @endcode
- *
- * Here, the instantiations provided are for <tt>number</tt> types
- * <tt>float</tt>, <tt>double</tt> and <tt>long double</tt>. Still,
- * there are more number types and somebody might want to use complex
- * polynomials. Therefore, complementing the declaration of
- * Polynomials::Polynomial in <tt>polynomial.h</tt>, there is a file
- * <tt>polynomial.templates.h</tt>, providing the implementation
- * source code.
+ * These are class templates usually having a small number of instantiations,
+ * but additional instantiations may be necessary. Therefore, a set of
+ * instantiations for the most likely parameters is provided precompiled in
+ * the libraries, but the implementation of the templates are provided in a
+ * special header file so that it is accessible in case someone wants to
+ * instantiate it for an unforeseen argument.
+ *
+ * Typical examples for this would be some of the linear algebra classes that
+ * take a vector type as template argument. They would be instantiated within
+ * the library for <code>Vector&lt;double&gt;</code>,
+ * <code>Vector&lt;float&gt;</code>, <code>BlockVector&lt;double&gt;</code>,
+ * and <code>BlockVector&lt;float&gt;</code>, for example. However, they may
+ * also be used with other vector types as long as they satisfy certain
+ * interfaces, including vector types that are not part of the library but
+ * possibly defined in an application program. In such a case, applications
+ * can instantiate these templates by hand as described in the next section.
+ * 
  *
  * @subsection Inst2c Creating new instances
  *
  * template class XXXX<Lager>;
  * @endcode
  *
+ * 
  * @subsection Inst2p Provided instances
  *
- * Like with the classes in section Inst1, the instances provided in
- * the library are often listed in the line pointing to this page,
- * that is for example:
+ * Like with the classes in section Inst1, the instances provided in the
+ * library are often listed in the documentation of that class in a form
+ * similar to this:
  @verbatim
- Template Instantiations: some  (<p1> <p2>)
+ Template Instantiations: some  (<p1>a,b,c<p2>)
  @endverbatim
  *
+ *
  * @section Inst3 Many instantiations
  *
- * These are the classes, where no reasonable predetermined set of
- * instances exists. Therefore, all member definitions are included
- * into the header file and are instantiated wherever needed.
- * For an example, see
- * @code
- * template<typename T> class SmartPointer;
- * @endcode
+ * These are the classes, where no reasonable predetermined set of instances
+ * exists. Therefore, all member definitions are included in the header file
+ * and are instantiated wherever needed.  An example would be the SmartPointer
+ * class template that can be used with virtually any template argument.
  */

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.