doc/annexe_common.rst

   1
   2 Appendix:  processing of fortran commons and C / C++ global variables
   3 ========================================================================
   4 Fortran common
   5 --------------
   6 This section is the result of studies carried out by Marc Boucker, Alexandre Douce, Céline Béchaud and Marc Tajchman
   7 (for further details, see [COMMON]_). We do not aim to present a complete state of possible situations in this description.
   8 The fortran 77 codes that are to be controlled from the python interpreter or from Corba / SALOME often define memory zones
   9 shared between the different fortran functions, called “common”.
  10 For example, functions ``f1`` and ``f2`` use the same memory zone ``a`` in common ``C``.
  11
  12 .. _f1:
  13
  14
  15 ``f1.f``
  16
  17 .. include:: ./exemples/exemple11/v1/f1.f
  18    :literal:
  19
  20 .. _f2:
  21
  22
  23 ``f2.f``
  24
  25 .. include:: ./exemples/exemple11/v1/f2.f
  26    :literal:
  27
  28 If the two functions are contained in the same component and common ``C`` is not used by functions of other components, the
  29 common is not visible from outside the component and “everything takes place properly” (see
  30 figure :ref:`Using a common in a component <figcommon0>`).  If the component designer wants to allow common to be read or
  31 written from the python and/or CORBA layer, he will easily be able to write access functions (for example ``setCommon`` and
  32 ``getCommon`` functions in the following example).
  33
  34 ``common.f``
  35
  36 .. include:: ./exemples/exemple11/v1/common.f
  37    :literal:
  38
  39 .. _figcommon0:
  40
  41
  42 .. image:: images/common0.png
  43    :align: center
  44
  45 .. centered:: Using a common in a component
  46
  47 The following is an example encapsulation in C++, then in python (through swig):
  48
  49
  50 ``f.hxx``
  51
  52 .. include:: ./exemples/exemple11/v1/f.hxx
  53    :literal:
  54
  55
  56 ``modf.i``
  57
  58 .. include:: ./exemples/exemple11/v1/modf.i
  59    :literal:
  60
  61 A practical example:
  62
  63 .. include:: ./exemples/exemple11/v1/resultats.txt
  64    :literal:
  65
  66 If common ``C`` is used in several dynamic libraries, management is more difficult.  In general, it is impossible
  67 to assume that the common used by each library is located at the same memory address.  There are two typical
  68 situations that can arise:
  69
  70 #. The two components are installed locally from the same python interpreter:
  71
  72      .. _figcommon1:
  73
  74
  75      .. image:: images/common1.png
  76         :align: center
  77
  78      .. centered:: Using a common shared between two libraries – Local version
  79
  80
  81 #. The two components are installed in different memory zones (on the same machine or on different machines) through
  82    the SALOME mechanism (containers):
  83
  84      .. _figcommon2:
  85
  86
  87      .. image:: images/common2.png
  88         :align: center
  89
  90      .. centered:: Using a common shared between two libraries – distributed version
  91
  92 Synchronization functions are necessary in both cases (for example using functions to read / write commons
  93 from the python and/or SALOME command layer).  The adaptation to the case of two local components loaded from a
  94 python interpreter is written as follows:
  95
  96 #. For the first component:
  97
  98    ``f1.hxx``
  99
 100    .. include:: ./exemples/exemple11/v2/f1.hxx
 101       :literal:
 102
 103
 104    ``modf1.i``
 105
 106    .. include:: ./exemples/exemple11/v2/modf1.i
 107       :literal:
 108
 109 #. For the second component:
 110
 111    ``f2.hxx``
 112
 113    .. include:: ./exemples/exemple11/v2/f2.hxx
 114       :literal:
 115
 116
 117    ``modf2.i``
 118
 119    .. include:: ./exemples/exemple11/v2/modf2.i
 120       :literal:
 121
 122 #. Read and write functions for the common will be included in each component.
 123
 124
 125 A practical example
 126
 127
 128 .. include:: ./exemples/exemple11/v2/resultats.txt
 129    :literal:
 130
 131 In summary, if an existing code comprising commons has to be broken down into several components, it is possible to either:
 132
 133 - modify the code by removing the commons and transferring information through lists of function parameters;
 134 - write functions to provide read/write access to the commons and use these read/write functions from layers higher
 135   than components, so as to synchronize the internal states of the different components.
 136
 137 The first solution requires that in-depth action is taken in the fortran code, while the second requires that the
 138 user explicitely synchronises commons in the different components.  It is strongly recommended that commons should not be
 139 used in new fortran codes.
 140
 141 C/C++ global variables
 142 ------------------------
 143 The situation is similar to the case of commons:  each component will have its own set of global variables.
 144 A method is necessary to assure that these different sets of variables are consistant.
 145