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{The {\classtitle Timer} class}
18
19The {\class Timer} class is a utility class to perform computational time analysis (cpu time
20and elapsed time) and manage dates. It uses the following data members which store time, cpu
21time and system time in various format.
22\vspace{.2cm}
23\begin{lstlisting}
24class Timer
25{private:
26    time_t t;                       //time type provided by ctime
27    tm localt;                      //time structure provided by ctime
28    long int sec_, microSec_;       //time in seconds and microseconds
29                                    // since 01/01/1970 00:00:00
30    long int usrSec_, usrMicroSec_; // cputime in seconds and microseconds
31                                    // since beginning of current process
32    long int sysSec_, sysMicroSec_; // system time in seconds and microseconds
33                                    // since beginning of current process
34 ...
35};
36\end{lstlisting}
37\vspace{.2cm}
38The {\class Timer} class has only one constructor (no argument) which initializes the start
39time. It provides a few basic functionalities:
40\vspace{.2cm}
41\begin{lstlisting}[]{}
42    void update()                // converts time to tm struct
43    int year()                   // year as an int
44    unsigned short int month()   // month as an int [0-11]
45    unsigned short int day()     // day of month as an int [0-31]
46    unsigned short int hour()    // hour of day (24h clock)
47    unsigned short int minutes() // minutes of hour [0-59]
48    unsigned short int seconds() // seconds of minute [0-59]
49    void getCpuTime()            // update cputime interval since beginning of process
50    double deltaCpuTime(Timer*)  // returns elapsed time interval since "ot" time
51    void getTime()               // update time in s and ms since 01/01/1970 00:00:00
52    double deltaTime(Timer*)     // returns elapsed time interval since "ot" time
53\end{lstlisting}
54\vspace{.2cm}
55Associated to these member functions, there are the following external functions (user functions):
56\vspace{.2cm}
57\begin{lstlisting}[]{}
58String theTime()           // returns current time
59String theDate()           // returns current date as dd.mmm.yyyy
60String theShortDate()      // returns current date as mm/dd/yyyy or dd/mm/yyyy
61String theLongDate()       // returns current date as Month Day,Year or Day Month Year
62String theIsoDate()        // returns ISO8601 format of current date (yyyy-mm-dd)
63String theIsoTime()        // returns ISO8601 format of current time (hh-mi-ss)
64
65double cpuTime()                   // returns cputime in sec.since last call
66double cpuTime(const String&)      // same and prints it with comment
67double totalCpuTime()              // returns cputime in sec.since first call
68double totalCpuTime(const String&) //same and prints it with comment
69double elapsedTime()               // returns elapsed time  in sec. since last call
70double elapsedTime(const String&)  // same and prints it with comment
71double totalElapsedTime()          // returns elapsed time in sec. since first call
72double totalElapsedTime(const String&) // returns elapsed time interval in sec.
73                                       // same and prints it with comment
74\end{lstlisting}
75\vspace{.2cm}
76
77Note that this class is OS dependant because Unix and Windows do not provide the same system
78time functions. The macro OS\_IS\_WIN32 set in \emph{setup.hpp} is used to select the right
79version.
80In particular, for Unix platform the class uses some functions provided by the header \emph{sys/time.h}
81and for Windows platform, some functions provided by the header \emph{sys/timeb.h,}, this header
82requiring the headers  \emph{windef.h, stdio.h, cstdarg, winbase.h}.\\
83
84The function \emph{timerInit()} in the \emph{init.cpp} file creates two {\class Timer}
85objects (\emph{theStartTime\_p} and \emph{theLastTime\_p}) at the beginning of the execution.
86These objects have a global scope and are used by the {\class Timer} class
87to make easier the time computation analysis for the user. There is no reason to create other
88instances of {\class Timer}. \\
89
90So, it is easy to the user to perform time computation analysis. For instance:
91\vspace{.2cm}
92\begin{lstlisting}[]{}
93#include "xlife++.h"
94using namespace xlifepp;
95int main()
96{
97  init(fr);  //initializes timers
98  //task 1
99  ...
100  cpuTime("cpu time for task 1");
101  elapsedTime("ellapsed time for task 1");
102  //task 2
103  ...
104  cpuTime("cpu time for task 2");
105  elapsedTime("ellapsed time for task 2");
106  //end of tasks
107  totalCpuTime("total cpu time");
108  totalElapsedTime("total ellapsed time");
109}
110\end{lstlisting}
111\vspace{.2cm}
112
113\displayInfos{library=utils, header=Timer.hpp, implementation=Timer.cpp, header dep={config.h}}
114
115