[Time4Tea]

I'm trying to read and understand some of the OpenFOAM source code (specifcally, version 6 from openfoam.org). I've chosen to start at pTraits.h, as it seems quite foundational. I was trying to understand some of the classes relating to vector fields and point fields, but they seem to be using this header as a base.


Anyway, I have some basic knowledge of C/C++; however, I am confused by some of the syntax that is being used:


Firstly, at line 44:

class Istream;

The Istream class clearly isn't being defined here; however, there are no other header file being included. Where does this Istream come from and what does it do? I can see that it is being used in one of the constructors further down.


Secondly, lines 52-53:

:
     public PrimitiveType

I don't understand what the colon means in the class template declaration, or what the 'public PrimitiveType' is for.



Also, to summarize what this header is doing: it is providing a basic template class, with a couple of constructors for primitive objects - is that correct?



In general, I'm not sure if this particular file is a good place to start delving into the OF codebase - any advice on that would be much appreciated.

[t.teschner]

these are just some c++ specific ways of doing things.

The "class Istream" is a forward declaration of the class Istream and is just here so that your linker doesn't complain. You could remove this and include a header file to the actual implementation of the class, i.e. put #include "IStream.H" at the top, but that includes the whole header. I guess it comes down to your personal preference and coding style, but generally speaking, for large projects such as openfoam you should try to avoid including header files and use forward declaration whenever possible.
The forward declared class just tells the linker not to complain and to assume that such a class exist. Of course, this class needs then to be declared somewhere else which the compiler / linker can find.

Regarding your second question, the construct

template<class A>
class B : public A

is used for static polymorphism. I am not sure how much you know about polymorphism in general (virtual functions, templates) which would also determine how much sense an explanation would make at this point, but basically, you can achieve static polymorphism through templates and dynamic polymorphism through the use of virtual functions.
The above construct allows you to use methods from class A in class B but you don't need to know what A is, you just need to make sure that it will have the required method that you want to call. The advantage here is, that class A can have many different versions while class B doesn't care what A is, it just makes use of its interface (data abstraction, another important concept in C++).

Now this all sounds very complicated and dry without an example, so lets say we want to write a CFD solver and we want to have different reconstruction / interpolation scheme, say a first and a second order accurate one. One way of implementing that with the structure given in the pTraits class could look like this:

#include <iostream>

class firstOrderReconstruction
{
  public:
    void reconstruct()
    {
      std::cout << "Implement a first order reconstruction here" << std::endl;
    }
};

class secondOrderReconstruction
{
  public:
    void reconstruct()
    {
      std::cout << "Implement a second order reconstruction here" << std::endl;
    }
};

template<class scheme>
class reconstructor : public scheme
{
  using scheme::reconstruct;
  public:
    void applyReconstruction()
    {
      reconstruct();
    }
};

int main()
{
  reconstructor<firstOrderReconstruction > firstOrder;
  reconstructor<secondOrderReconstruction> secondOrder;

  firstOrder.applyReconstruction(); // will print "Implement a first order reconstruction here"
  secondOrder.applyReconstruction(); // will print "Implement a second order reconstruction here"
  return 0;
}

so basically we provide two implementations for the reconstruction class (a first and second order one) and just by specifying it as the template argument we now have a first or second order accurate reconstruction scheme. If you look at the class "reconstructor", it inherits from its template argument but it doesn't know if it is first or second order. This makes the code less readable but more performance optimised because templates are resolved at compile time, meaning that each possible combination (here we only have two, the first and second order reconstruction class as a template argument) will be compiled and this at run time the correct version will be selected. this is performance optimised because we decide at compile time which version we use, the more "C" style way of doing things here would be to use an if clause, or a switch / case statement, but that would incur a runtime overhead and thus would be slower.
As a side note, you could have achieved the same behaviour above with dynamic runtime polymorphism, i.e. using virtual functions, that would have looked like this

#include <iostream>

class reconstructor
{
  public:
    // we could also drop the = 0 at the end, but in this way we force 
    // all classes that derive from this to implement this virtual function
    // (now called a pure virtual function)  
    virtual void applyReconstruction() = 0;
};

class firstOrderReconstruction : public reconstructor
{
  public:
    void applyReconstruction() final override
    {
      std::cout << "Implement a first order reconstruction here" << std::endl;
    }
};

class secondOrderReconstruction : public reconstructor
{
  public:
    void applyReconstruction() final override
    {
      std::cout << "Implement a second order reconstruction here" << std::endl;
    }
};

int main()
{
  firstOrderReconstruction  firstOrder;
  secondOrderReconstruction secondOrder;

  firstOrder.applyReconstruction(); // will print "Implement a first order reconstruction here"
  secondOrder.applyReconstruction(); // will print "Implement a second order reconstruction here"
  return 0;
}

Similar, but there is a difference in the execution again. Virtual functions get resolved at runtime, i.e. when we call firstOrder.applyReconstruction() for example, only then do we lookup which version we actually want to call (i.e. which class is overriding the virtual function in the base class reconstructor). Templates do that at compile time, not at runtime, thus we say virtual functions follow dynamic polymorphism while templates can be used (and abused) to give you static polymorphism.

Fairly exhaustive, but I feel that c++ question are rarely answered in just two sentences. Hope that that gives you a better idea.

[Time4Tea]

Hi t.teschner, thank you very much for the great explanation, with the examples. This is very helpful, thank you.


I think I have a basic understanding of Polymorphism and Inheritance, but I am reading some more into them and how they are implemented in C++. I'm getting the impression that OF makes quite extensive use of these concepts, so I will need to understand them more deeply.


Your explanation and examples of the polymorphism are very helpful. So, the pTraits class can inherit from a range of different classes and 'PrimitiveType' is the template 'placeholder' for the type of class it inherits from?



One thing I am still a bit confused about though is what the pTraits class is doing. It seems to be inheriting these two constructors from whichever class PrimitiveType is referring to (the first one looks like a copy constructor - is that correct?). However, as far as I can see, it doesn't seem to be modifying them in any way. So, what is the function of the pTraits class?

[t.teschner]

Yes, openfoam and makes great use of C++'s object orientated features (which allows us to type our equations in a pain-free manner ...). And yes, you can see the template parameter as a placeholder, that is exactly what they are.

I don't have the code currently in front of me but I would guess that this class just provides an interface for other classes which derive from this class (so that any derived class has a constructor that accepts the template argument's parameter or an Istream object). So its use would have to be evaluate in the context of a derived class. The term copy constructor is not correct in this context, for that the constructor would accept an argument of the class itself, i.e. the copy constructor would look something like pTraits(pTraits& p).

Hope this helps.