1 #ifndef __CS_TIMER_H__
2 #define __CS_TIMER_H__
3
4 /*============================================================================
5 * Program timing information
6 *============================================================================*/
7
8 /*
9 This file is part of Code_Saturne, a general-purpose CFD tool.
10
11 Copyright (C) 1998-2021 EDF S.A.
12
13 This program is free software; you can redistribute it and/or modify it under
14 the terms of the GNU General Public License as published by the Free Software
15 Foundation; either version 2 of the License, or (at your option) any later
16 version.
17
18 This program is distributed in the hope that it will be useful, but WITHOUT
19 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21 details.
22
23 You should have received a copy of the GNU General Public License along with
24 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25 Street, Fifth Floor, Boston, MA 02110-1301, USA.
26 */
27
28 /*----------------------------------------------------------------------------*/
29
30 /*----------------------------------------------------------------------------
31 * Local headers
32 *----------------------------------------------------------------------------*/
33
34 #include "cs_defs.h"
35
36 /*----------------------------------------------------------------------------*/
37
38 BEGIN_C_DECLS
39
40 /*============================================================================
41 * Public types
42 *============================================================================*/
43
44 /* Information structure for precise timings */
45
46 typedef struct {
47
48 long long sec; /* seconds */
49 long long nsec; /* nanoseconds */
50
51 } cs_timer_t;
52
53 /* Information structure for timing counters */
54
55 typedef struct {
56
57 long long nsec; /* wall-time nanoseconds */
58
59 } cs_timer_counter_t;
60
61 /*============================================================================
62 * Public macros
63 *============================================================================*/
64
65 /*----------------------------------------------------------------------------
66 * Initialize timer counter.
67 *
68 * parameters:
69 * _t --> resulting counter.
70 *----------------------------------------------------------------------------*/
71
72 #define CS_TIMER_COUNTER_INIT(_t) \
73 (_t.nsec = 0)
74
75 /*----------------------------------------------------------------------------
76 * Add timer counter.
77 *
78 * The result may be identical to one of the 2 counters to add.
79 *
80 * parameters:
81 * _res --> resulting counter.
82 * _c0 <-- counter to add.
83 * _c1 <-- counter to add.
84 *----------------------------------------------------------------------------*/
85
86 #define CS_TIMER_COUNTER_ADD(_res, _c0, _c1) \
87 (_res.nsec = _c0.nsec + _c1.nsec)
88
89 /*============================================================================
90 * Public function prototypes
91 *============================================================================*/
92
93 /*----------------------------------------------------------------------------
94 * Return Wall clock time
95 *
96 * returns:
97 * elapsed time from first call of a function of the cs_timer_...()
98 * series, or -1 if unable to compute.
99 *----------------------------------------------------------------------------*/
100
101 double
102 cs_timer_wtime(void);
103
104 /*----------------------------------------------------------------------------
105 * Return CPU time.
106 *
107 * Note that in the rare case that only the minimal C library clock()
108 * method is available (see cs_timer_cpu_time_method()), at least one of
109 * the cs_timer_...() functions (possibly this one) must be called
110 * upon program start for this function to be used. In addition,
111 * in this case, time may "loop" back to 0 every multiple of
112 * 2^size_t / CLOCKS_PER_SEC seconds.
113 *
114 * returns:
115 * current CPU time usage, or -1 if unable to compute.
116 *----------------------------------------------------------------------------*/
117
118 double
119 cs_timer_cpu_time(void);
120
121 /*----------------------------------------------------------------------------
122 * Return separate user and system CPU times.
123 *
124 * parameters:
125 * user_time --> current user CPU usage.
126 * system_time --> current system CPU usage.
127 *----------------------------------------------------------------------------*/
128
129 void
130 cs_timer_cpu_times(double *user_time,
131 double *system_time);
132
133 /*----------------------------------------------------------------------------
134 * Return a timer's value
135 *
136 * returns:
137 * timer structure.
138 *----------------------------------------------------------------------------*/
139
140 cs_timer_t
141 cs_timer_time(void);
142
143 /*----------------------------------------------------------------------------
144 * Compute the difference between 2 timers.
145 *
146 * parameters:
147 * t0 <-- oldest timer value
148 * t1 <-- most recent timer value
149 *
150 * returns:
151 * last - first timer value.
152 *----------------------------------------------------------------------------*/
153
154 cs_timer_counter_t
155 cs_timer_diff(const cs_timer_t *t0,
156 const cs_timer_t *t1);
157
158 /*----------------------------------------------------------------------------
159 * Add the the difference between 2 timers to a counter.
160 *
161 * parameters:
162 * tc <-> pointer to timer counter
163 * t0 <-- oldest timer value
164 * t1 <-- most recent timer value
165 *
166 * returns:
167 * last - first timer value.
168 *----------------------------------------------------------------------------*/
169
170 static inline void
cs_timer_counter_add_diff(cs_timer_counter_t * tc,const cs_timer_t * t0,const cs_timer_t * t1)171 cs_timer_counter_add_diff(cs_timer_counter_t *tc,
172 const cs_timer_t *t0,
173 const cs_timer_t *t1)
174 {
175 tc->nsec += (t1->sec - t0->sec) * (long long)1000000000
176 + t1->nsec - t0->nsec;
177 }
178
179 /*----------------------------------------------------------------------------
180 * Return method used to return wall clock time.
181 *
182 * Note that in the rare case that only the minimal C library clock()
183 * method is available, this function will return -1 values.
184 *
185 * returns:
186 * short description of method used to return wall clock time.
187 *----------------------------------------------------------------------------*/
188
189 const char *
190 cs_timer_wtime_method(void);
191
192 /*----------------------------------------------------------------------------
193 * Return method used to return CPU time.
194 *
195 * returns:
196 * short description of method used to return CPU time.
197 *----------------------------------------------------------------------------*/
198
199 const char *
200 cs_timer_cpu_time_method(void);
201
202 /*----------------------------------------------------------------------------*/
203
204 END_C_DECLS
205
206 #endif /* __CS_TIMER_H__ */
207