source: Sophya/trunk/DocHFI_L2/sdg.tex@ 1399

\documentclass[twoside,12pt]{article}
%  Package standard : Utilisation de caracteres accentues, mode francais et graphique
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{graphicx}

%  Extension de symboles mathematiques
\usepackage{amssymb}

% package a mettre pour faire du pdf
\usepackage{palatino}

%  Definition de taille de page
\setlength{\textwidth}{16cm}
\setlength{\textheight}{21.5cm}
\setlength{\topmargin}{0.5cm}
\setlength{\oddsidemargin}{0.cm}
\setlength{\evensidemargin}{0.cm}
\setlength{\unitlength}{1mm}

\newcommand{\bul}{$\bullet \ $}

\begin{document}

\begin{titlepage}
\vspace{1cm}
\vspace{1cm}
\makebox[34mm][c]{\includegraphics[width=3cm]{hfi_icon_vsmall.eps}}
\raisebox{12mm}{\rule{80 mm}{0.5 mm}\makebox[50 mm]{\bf Planck HFI L2}}
\vspace{2cm}
\vspace{2cm}
\begin{center}
\par \renewcommand{\baselinestretch}{2.0} \small 
{\LARGE \bf 
Planck HFI L2 \\ 
Software Development Guidelines
}
\par \renewcommand{\baselinestretch}{1.0} \normalsize
\vspace{5 cm}
\begin{tabular}{ll}
{R. Ansari} & {\tt ansari@lal.in2p3.fr} \\
{É. Aubourg} & {\tt aubourg@hep.saclay.cea.fr} \\
% {É. Lesquoy} & {\tt lesquoy@hep.saclay.cea.fr} \\
{C. Magneville} & {\tt cmv@hep.saclay.cea.fr} \\
\end{tabular}

\end{center}
\vfill
\hfill 
% \includegraphics[width=4cm]{Fig/hfi_icon_vsmall.eps}
\framebox[\textwidth]{\hspace{0.5cm} \bf Planck HFI Level 2 
\hspace{1cm} \today }
\end{titlepage}

\tableofcontents

\newpage

\section{Introduction}
We intend to gather gradually in this document the guidelines 
for the development of Planck HFI Level 2 data processing software.
We assume throughout this document that C++ is the baseline option
as the programming language for the development of Planck HFI 
Level 2 processing software, we review here briefly some of 
the properties of the C++ and Java language and interoperability
with other language, mainly C and Fortran.


\section{C++}
{\bf C++ \ } is an object-oriented programming language which 
has been developed by extending the {\bf C \ } language.
Some of the additional possibilities incorporated in C++ are:
\begin{itemize}
\item Introduction of object and classes
\item function overloading
\item Operator overloading
\item function and operator inlining 
\item virtual functions (polymorphism)
\item public, protected and private members
\item dynamic memory management operators
\item Exception handling
\item generic (template) function and classes
\end{itemize}

We discuss here the some of the problems and solutions arising when 
integrating software modules written in other languages into C++ programs.

\subsection{Calling C code from C++} 
C++ extends the possibilities offered by the C language. 
All of the C language data types and function call syntax are thus 
supported by C++. Among other features, C++ offers the function 
overloading possibility. This means that functions with different 
argument list can have the same name.
\begin{verbatim} 
int fo(int a);
int fo(int a, int b);
int fo(double a, double b);
\end{verbatim}
Using {\bf C \ }, one would have written:
\begin{verbatim} 
int foi(int a);
int foii(int a, int b);
int fodd(double a, double b);
\end{verbatim}
C++ compilers use internally a name containing the encoding of the
argument list. In order to instruct the compiler to use simple 
names, {\bf C \ } functions should be declared as \\
{\tt extern "C" }. This is usually included in the header
file (.h). In the example above, the header file (.h) file
would be in the form:
\begin{verbatim} 
#ifdef __cplusplus
extern "C" {
#endif
int foi(int a);
int foii(int a, int b);
int fodd(double a, double b);
#ifdef __cplusplus
}
#endif
\end{verbatim}

\subsection{Calling Fortran code from C++}
Fortran is a simple language and uses only basic data types.
Although the exact mapping between Fortran and C/C++ basic data types 
may vary depending on the OS and hardware architecture, it is close
to the one shown in the table below: 
\begin{center}
\begin{tabular}{lll}
INTEGER     &  int    & usually 4 bytes \\
REAL*4      &  float  & usually 4 bytes \\
REAL*8      &  double & usually 8 bytes \\
COMPLEX     &  complex<float> & \\
COMPLEX*16  &  complex<double> & \\
\end{tabular}
\end{center}
In fortran, all arguments are passed by address and 
fortran compilers (on Unix systems) add an underscore "\_"
to all symbol names. It is thus rather easy to call 
Fortran subroutines or functions from C or C++. 
This is illustrated in the following example:
\begin{verbatim}
C   Fortran-Code
      SUBROUTINE FSUB(A,N,B,M)
      REAL A(*),B(*)
      INTEGER N,M
      RETURN
      END
\end{verbatim}
The corresponding C (or C++) declaration is: \\[3mm]
{\tt void fsub\_(float *a, int *n, float *b, int *m); } \\[3mm]
{\tt FSUB} can be called from C code, as is shown below : 
\begin{verbatim}
float aa[10];
int na=10;
float bb[10];    
int mb=10;
fsub_(aa, &na, bb, &mb);
\end{verbatim}

The case of character string arguments in Fortran subroutines
needs a bit more attention, and the string length needs to be passed 
as an additional integer type argument.
As with {\bf C \ } functions, Fortran functions or subroutines 
have to be declared {\tt extern "C"} to be used within {\bf C++ \ }
programs. {\bf C/C++ \ } driver routines can easily be written for
extensively used Fortran modules, simplifying calling sequences.

It should also be noted that the Fortran support libraries have to be 
included for the link with the C++ driver.
It is also possible to translate the whole Fortran source code 
into {\bf C \ } code using {\bf f2c \ } program. The call syntax 
will be exactly the same as with a Fortran compiler, and 
{\tt libf2c.a} should be used when linking the program.

It is very difficult to use C++ classes directly from Fortran.
However, high level functionalities based on a C++ library can 
be wrapped in a Fortran style function which can be 
called from Fortran. One looses of course many of the 
possibilities offered by underlying C++ library.

We illustrate below the wrapping of a simple C++ class:
\begin{verbatim}
// An example class performing some computation
class Example {
  Example();
  ~Example();
  void compute(int sz, float *x);
  int getSize();
  float getResult(int k);
};
\end{verbatim}

The wrapper would then look like:
\begin{verbatim}
extern "C" {
  void foradapt_(float *a, int *n, float *b, int *m);
}

foradapt_(float *a, int *m, float *b, int *n)
{
// a is the input array, m it's size
// b is the output array, n the returned size
// b has to dimensioned big enough in the calling program

Example ex;
ex.compute(*n, a);
*m = ex.getSize();
for(int i=0; i<ex.getSize(); i++) 
  b[i] = ex.getResult(i);
}
\end{verbatim}

One can then call {\tt FORADPAT} from fortran :
\begin{verbatim}
REAL  A(1000)
REAL  B(1000)
INTEGER N,M
M = 1000
N = 1000
CALL FORADPAT(A, M, B, N)
\end{verbatim}


\subsection{Fortran-90 and C++}
Fortran-90 (F90) is a much more complex language than Fortran 77
(F77). Compared to F77, it introduces many new constructions, including:
\begin{itemize}
\item[-] pointers 
\item[-] local and global variables
\item[-] in, out, in-out argument type for function and subroutines
\item[-] compound data types, similar to structures in C 
\item[-] multidimensional arrays
\item[-] function and operator overloading.
\end{itemize}
It is thus more difficult to use full featured F90 modules from 
{\bf C} or {\bf C++}. One would have to map all these different 
data structures with their attributes between the two languages,
in a OS/compiler independent way.
It should however be possible to encapsulate F90 modules into simple F77 
like subroutines that could be called from C/C++. 


\section{Java}
Java \footnote{Information on the Java platform and language 
can be found at {\bf http://java.sun.com} }
is a rather recent object-oriented programming language. It is 
based on the concept of a virtual machine, and a very extended 
standard library.

Java compilers produce "byte-codes" that are interpreted in a virtual 
machine (JVM). Thus, pure Java programs are platform-independent and 
portable. The very extended libraries that are available for the 
language make it a very good choice for user interfaces, network 
programming, distributed objects, database access. Numeric 
computation libraries start to appear but are still in early stages 
of development.

The Java language is strongly typed, with dynamic typing information. 
It is dynamic in essence as class bytecodes can be loaded into the 
JVM on request.
It uses a garbage collector for memory management. Memory leaks and 
memory access errors cannot exist. All this makes debugging easier 
than with C++.

The overhead of interpreting the bytecodes in the virtual machine is 
alleviated by the development of "JIT" (Just In Time) compilers, that 
do a dynamic compilation. Java programs are typically 3 times slower 
than their equivalent in C++, but the exact figure might vary between 
1 and 5 depending on the type of program.

Two features convenient for numeric library development and usage 
present in C++ are missing in Java: templates and operator overloading. 
Typically, a single code cannot be specialised for 
floats and doubles automatically, and one must write, if A, B and C 
are matrices, {\tt C = A.mult(B) instead of C = A*B} . 

\subsection{Calling C/C++ code from Java }

A Java library (JNI, Java Native Interface) allows to call C/C++ code 
from Java programs. Of course, portability is then lost.
Methods in Java objects can be declared {\tt native}. A tool then 
produces C/C++ headers for coding these methods in C/C++. This code 
can call existing C/C++/Fortran code, and even map the Java object to 
a C++ object.

Because the layout of objects in memory is not fixed in the JVM 
specifications, all accesses to methods and member variables are done 
through interface pointers. Accessing arrays can imply a copy of the 
array on input, and a copy back on return if the array was modified.

Since Java memory management is garbage-collector-based, C/C++ 
programs that want to hold references to Java objects, or create Java 
objects, must interact with the garbage collector explicitly.

JNI allows also C/C++ programs to instantiate a JVM and Java objects, 
and access them.

\subsection{Java and CORBA}

Another solution to call C++ objects from Java, or vice-versa, is to 
use CORBA. CORBA is a standard distributed objects framework, and 
Java 2 comes with a CORBA-2 compliant ORB (Object Request Broker), 
JavaIDL.

Objects distributed through CORBA must have their interface defined 
in a specific language, IDL. Tools then creates stubs for any 
language, as well as implementation skeletons.

An object can then physically exist on a machine, implemented in C++, 
and be manipulated remotely through Java stubs, as if it were a local 
Java object. CORBA offers thus language-independent distributed 
objects.

It adds overhead compared to JNI, because of the presence of a 
network layer, but offers more functionality. In particular, the C++ 
objects are platform-dependent, but the Java code that uses them, 
being pure Java code, remains portable.


\newpage
\appendix

\section{C++ standard and compilers}
\vspace{5 mm}

{\bf C++} can be considered now as a mature language. 
The current standard for C++ and C are defined by
\footnote{Available from {\bf http://www.ansi.org/ } }: 
\begin{itemize}
\item[] {\bf ISO/IEC 14882-1998(E) \ } Programming languages -- C++ 
\item[] {\bf ANSI/ISO 9899-1990 \ } for Programming Languages C  
\end{itemize}

Powerful compilers are available on most platforms, including:

\begin{itemize}
\item[-] the GNU multiplatform g++ \footnote{http://gcc.gnu.org/},
\item[-] KAI KCC \footnote{http://www.kai.com/C\_plus\_plus/} which is a 
nice multiplatform optimising C++ compiler.
\item[-] Digital (Compaq) cxx \footnote{http://www.unix.digital.com/cplus/}
\item[-] IBM VisualAge C++ \footnote{http://www-4.ibm.com/software/ad/vacpp/}
\item[-] HP aCC \footnote{http://www.hp.com/esy/lang/cpp/}
\item[-] Silicon Graphics SGI-CC on IRIX \footnote{http://www.sgi.com/developers/devtools/languages/c++.html} 
\item[-] Cray C++ compiler on Unicos \footnote{http://www.sgi.com/software/unicos/cplusoverview.html}
\end{itemize} 


\end{document}