From 541c3976967783c0200edaed2bf6238b3beb94c9 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Fri, 20 Jan 2006 16:50:23 +0000 Subject: [PATCH] Explain a little better what is going on. git-svn-id: https://svn.dealii.org/trunk@12112 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/doxygen/headers/instantiations.h | 124 +++++++++---------- 1 file changed, 60 insertions(+), 64 deletions(-) diff --git a/deal.II/doc/doxygen/headers/instantiations.h b/deal.II/doc/doxygen/headers/instantiations.h index 8a19b93732..836cb2f7e3 100644 --- a/deal.II/doc/doxygen/headers/instantiations.h +++ b/deal.II/doc/doxygen/headers/instantiations.h @@ -1,26 +1,18 @@ /** * @page Instantiations Template instantiations * - *

Contents

- *
    - *
  1. @subpage Inst1 "Few" - *
  2. @subpage Inst2 "Some" - *
  3. @subpage Inst3 "Many" - *
  4. - * - * 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 deal.II 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 deal.II 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 @@ -28,50 +20,55 @@ * template 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 .cc file in the - * source directory and all instantiations are in the source file. + * 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 .cc 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 deal.II 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 dim, the available instances * are for dim=1,2,3, if there is no other information. * - * For other classes, the list of available instances is often listed - * in the line - @verbatim - Template Instantiations: few ( ) - @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 + * double, float, and in some cases long + * double. + * * * @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 class Polynomials::Polynomial; - * @endcode - * - * Here, the instantiations provided are for number types - * float, double and long double. Still, - * there are more number types and somebody might want to use complex - * polynomials. Therefore, complementing the declaration of - * Polynomials::Polynomial in polynomial.h, there is a file - * polynomial.templates.h, 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 Vector<double>, + * Vector<float>, BlockVector<double>, + * and BlockVector<float>, 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 * @@ -91,22 +88,21 @@ * template class XXXX; * @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 ( ) + Template Instantiations: some (a,b,c) @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 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. */ -- 2.39.5