1%%%%%%%%%%%%%%%%%%%
2% XLiFE++ is an extended library of finite elements written in C++
3%     Copyright (C) 2014  Lunéville, Eric; Kielbasiewicz, Nicolas; Lafranche, Yvon; Nguyen, Manh-Ha; Chambeyron, Colin
4%
5%     This program is free software: you can redistribute it and/or modify
6%     it under the terms of the GNU General Public License as published by
7%     the Free Software Foundation, either version 3 of the License, or
8%     (at your option) any later version.
9%     This program is distributed in the hope that it will be useful,
10%     but WITHOUT ANY WARRANTY; without even the implied warranty of
11%     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12%     GNU General Public License for more details.
13%     You should have received a copy of the GNU General Public License
14%     along with this program.  If not, see <http://www.gnu.org/licenses/>.
15%%%%%%%%%%%%%%%%%%%
16
17\section{Managing traces}
18
19\subsection{The {\classtitle Trace} class}
20
21The {\class Trace} class is devoted to keep trace of runtime of the hierarchy of function calls.
22Thus, we can have access to a stack of called functions, the next position to be used and the
23last one. Thus, this class proposes as members:
24\vspace{.1cm}
25\begin{lstlisting}
26class Trace {
27  private:
28    number_t pos_;                    //!< next position in trace object list member
29    static const number_t maxPos_=36; //!< last position in trace object list member
30    String fList[maxPos_];            //!< stack of called functions
31
32    static const String theLogFile_;  //!< name of log file
33    static bool isLogged_;
34
35  public:
36    static std::ofstream theLogStream_;
37  ...
38};
39\end{lstlisting}
40\vspace{.2cm}
41It offers:
42
43\begin{itemize}
44\item a default constructor that initializes pos\_ to 0, and private copy constructor and assignment
45operator
46\item some public access functions to data:
47\begin{lstlisting}[]{}
48static const String logFile() { return theLogFile_; }
49static bool isLogged() { return isLogged_; }
50static void logOn() { isLogged_ = true; }
51static void logOff() { isLogged_ = false; }
52number_t length() const; //!< function length returns the number of items of f_list
53\end{lstlisting}
54\vspace{.2cm}
55\item some public utilities methods for adding trace or having info on current position:
56\vspace{.1cm}
57\begin{lstlisting}[]{}
58void push(const String&);       //!< "pushes" name into Trace function list member
59void pop();                     //!< "pops" current input out of a Trace function list member
60String current(const number_t); //!< returns string of last l to current inputs of a Trace object list
61String current();               //!< returns last input string of a Trace object list
62String list();                  //!< returns function list of a Trace object list
63 \end{lstlisting}
64\vspace{.2cm}
65\item some public display management methods:
66\vspace{.1cm}
67\begin{lstlisting}
68void indent();                  //!< function indent prints context-depending indentation to log file
69void print(std::ofstream&);     //!< prints function list to opened ofstream or to default print file
70void print();
71\end{lstlisting}
72\vspace{.2cm}
73\item some public methods to build log messages:
74\vspace{.1cm}
75\begin{lstlisting}
76void log(); //!< outputs indentation to log file
77template<typename T_0> void log(const T_0& s);
78template<typename T_0, typename T_1>  void log(const T_0& s, const T_1& t1)
79template<typename T_0, typename T_1, typename T_2> void log(const T_0& s, const T_1& t1, const T_2& t2);
80template<typename T_0, typename T_1, typename T_2, typename T_3> void log(const T_0& s, const T_1& t1, const T_2& t2, const T_3& t3);
81template<typename T_0, typename T_1, typename T_2, typename T_3, typename T_4> void log(const T_0& s, const T_1& t1, const T_2& t2, const T_3& t3, const T_4& t4);
82\end{lstlisting}
83\vspace{.2cm}
84\item some external functions to manage trace errors:
85\vspace{.1cm}
86\begin{lstlisting}
87void incompleteFunction(const String& s = "");
88void invalidFunction(const String& s = "");
89void constructorError();
90set setNewHandler();
91\end{lstlisting}
92\vspace{.2cm}
93\item some external functions to manage verbose level:
94\vspace{.1cm}
95\begin{lstlisting}
96void setGlobalVerboseLevel(const unsigned int);
97unsigned int verboseLevel(const unsigned int);
98\end{lstlisting}
99\vspace{.2cm}
100\item one external functions to manage  the message location :
101\vspace{.1cm}
102\begin{lstlisting}
103String & where(const String& s);
104\end{lstlisting}
105\end{itemize}
106
107\subsection{How to use the verbose level ?}
108
109The verbose level is managed through 2 global variables : {\tt theVerboseLevel} and {\tt theGlobalVerboseLevel}, and 2 functions. The behavior is the following :
110
111\begin{itemize}
112\item To set globally the maximum verbose level to an int value $i$, you can use the following syntax : \lstinline{setGlobalVerboseLevel(i);} This sets the variable {\tt theGlobaVerboseLevel} and overrides every local definition of the verbose level to higher values. This function is to be used once at the beginning of a main program.
113\item To set locally the maximum verbose level to a value $i$, you can use the following syntax :
114\begin{lstlisting}
115int j=verboseLevel(i);
116if (i < theGlobalVerboseLevel) {
117  j=theVerboseLevel}=i;
118} else {
119  j=theGlobaVerboseLevel;
120}
121\end{lstlisting}
122\item To get the current maximum verbose level, you can use directly the variable {\tt theVerboseLevel}
123\end{itemize}
124
125\subsection{How to know where does messages come ?}
126
127To see how to throw messages, please read the previous section about it. Here, we will discuss how a message knows where it is and how to give is more information about it.
128
129The main mechanism is to use the functions {\cmd push} and {\cmd pop} respectively at the beginning and the end of whatever function. This piece of information is dealt with by messages handlers automatically. But we cannot do it for every function in the code. We have to reserve it for the top-level functions in order not to slow execution.
130
131For the deepest functions, there is another way : using the {\cmd where} function. This function is to be used just before a message call where {\cmd push} and {\cmd pop} are not used. Messages will deal with this additional information automatically. As a result, there is no need to define message format with the routine name as message data.
132
133\displayInfos{library=utils, header=Trace.hpp, implementation=Trace.cpp, header dep={config.h,
134String.hpp}}
135
136