7.0
general documentation
cs_log.h
Go to the documentation of this file.
1 #ifndef __CS_LOG_H__
2 #define __CS_LOG_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 #include "cs_timer.h"
36 #include "stdarg.h"
37 
38 /*----------------------------------------------------------------------------*/
39 
41 
42 /*============================================================================
43  * Public types
44  *============================================================================*/
45 
46 /* Code_Saturne log file types */
47 
48 typedef enum {
49 
50  CS_LOG_DEFAULT, /* Default (main) log */
51  CS_LOG_SETUP, /* Calculation setup and options log */
52  CS_LOG_PERFORMANCE, /* Performance log */
53  CS_LOG_N_TYPES /* Number of log file types */
54 
55 } cs_log_t;
56 
57 extern int cs_glob_log_frequency;
58 
59 /*============================================================================
60  * Public macros
61  *============================================================================*/
62 
63 /*============================================================================
64  * Public function prototypes
65  *============================================================================*/
66 
67 /*----------------------------------------------------------------------------*/
77 /*----------------------------------------------------------------------------*/
78 
79 void
80 cs_log_default_activate(bool activate);
81 
82 /*----------------------------------------------------------------------------*/
91 /*----------------------------------------------------------------------------*/
92 
93 bool
95 
96 /*----------------------------------------------------------------------------
97  * Count printable length of a character string.
98  *
99  * This should also include UTF-8 strings.
100  *
101  * parameters:
102  * str <-- pointer to printable string
103  *
104  * returns:
105  * printable length of character string
106  *----------------------------------------------------------------------------*/
107 
108 size_t
109 cs_log_strlen(const char *s);
110 
111 /*----------------------------------------------------------------------------
112  * Pad a string so that its printable length is the required length.
113  *
114  * This allows pretty-printing with UTF-8 strings, whose actual length may be
115  * larger than their printable length in the presence of multibyte characters.
116  *
117  * If either the printable length of the string is longer than the target
118  * width or the actual length is long than the destination buffer's size,
119  * it is truncated.
120  *
121  * parameters:
122  * dest --> pointer to destination buffer
123  * str <-- pointer to printable string
124  * width <-- desired printed length
125  * destsize <-- destination buffer size
126  *----------------------------------------------------------------------------*/
127 
128 void
129 cs_log_strpad(char *dest,
130  const char *src,
131  size_t width,
132  size_t destsize);
133 
134 /*----------------------------------------------------------------------------
135  * Pad a string on the left so that its printable length is
136  * the required length.
137  *
138  * This allows pretty-printing with UTF-8 strings, whose actual length may be
139  * larger than their printable length in the presence of multibyte characters.
140  *
141  * If either the printable length of the string is longer than the target
142  * width or the actual length is long than the destination buffer's size,
143  * it is truncated.
144  *
145  * parameters:
146  * dest --> pointer to destination buffer
147  * str <-- pointer to printable string
148  * width <-- desired printed length
149  * destsize <-- destination buffer size
150  *----------------------------------------------------------------------------*/
151 
152 void
153 cs_log_strpadl(char *dest,
154  const char *src,
155  size_t width,
156  size_t destsize);
157 
158 /*----------------------------------------------------------------------------*/
165 /*----------------------------------------------------------------------------*/
166 
167 void
168 cs_log_binary_pp_int32(int32_t code,
169  char buf[33]);
170 
171 /*----------------------------------------------------------------------------*/
187 /*----------------------------------------------------------------------------*/
188 
189 int
191  const char *format,
192  va_list arg_ptr);
193 
194 /*----------------------------------------------------------------------------
195  * Print log info to a given log type.
196  *
197  * The format and variable arguments are similar to those of the printf()
198  * type functions.
199  *
200  * In parallel, output is only handled by rank 0.
201  *
202  * parameters:
203  * format <-- format string, as printf() and family.
204  * ... <-- variable arguments based on format string.
205  *
206  * returns:
207  * number of characters printed, not counting the trailing '\0' used
208  * to end output strings
209  *----------------------------------------------------------------------------*/
210 
211 #if defined(__GNUC__)
212 
213 int
215  const char *format,
216  ...)
217  __attribute__((format(printf, 2, 3)));
218 
219 #else
220 
221 int
223  const char *format,
224  ...);
225 
226 #endif
227 
228 
229 /*----------------------------------------------------------------------------
230  * Flush for output of cs_log_printf() with modifiable behavior.
231  *
232  * If the argument is set to CS_LOG_N_TYPES, all log files are flushed.
233  *
234  * returns:
235  * 0 upon successful completion 0 is returned. Otherwise, EOF is returned
236  * and errno is set to indicate the error.
237  *----------------------------------------------------------------------------*/
238 
239 int
241 
242 /*----------------------------------------------------------------------------
243  * Print a separator line in a log file
244  *
245  * In parallel, output is only handled by rank 0.
246  *
247  * parameters:
248  * log <-- log file type
249  *----------------------------------------------------------------------------*/
250 
251 void
253 
254 /*----------------------------------------------------------------------------
255  * Output timing data block to a given log.
256  *
257  * If the optional array of call counters is used, only lines
258  * with a number of calls greater than 0 are logged.
259  *
260  * In parallel, output is only handled by rank 0.
261  *
262  * parameters:
263  * log <-- log file type
264  * indent <-- indentation before first column
265  * header_title <-- title for optional header line
266  * calls <-- true if calls column is to be used
267  *----------------------------------------------------------------------------*/
268 
269 void
271  int indent,
272  const char *header_title,
273  bool calls);
274 
275 /*----------------------------------------------------------------------------
276  * Output timing data block to a given log.
277  *
278  * If the optional array of call counters is used, only lines
279  * with a number of calls greater than 0 are logged.
280  *
281  * In parallel, output is only handled by rank 0.
282  *
283  * parameters:
284  * log <-- log file type
285  * indent <-- indentation before first column
286  * n_lines <-- number of lines in array, excluding header
287  * line_titles <-- array of titles for data lines
288  * calls <-- optional array of call counters, or NULL
289  * time_count <-- array of time counters
290  *----------------------------------------------------------------------------*/
291 
292 void
294  int indent,
295  int n_lines,
296  const char *line_titles[],
297  const unsigned calls[],
298  const cs_timer_counter_t time_count[]);
299 
300 /*----------------------------------------------------------------------------*/
301 
303 
304 #endif /* __CS_LOG_H__ */
Definition: cs_log.h:51
void cs_log_timer_array(cs_log_t log, int indent, int n_lines, const char *line_titles[], const unsigned calls[], const cs_timer_counter_t time_count[])
Output timing data block to a given log.
Definition: cs_log.c:673
Definition: cs_log.h:53
#define BEGIN_C_DECLS
Definition: cs_defs.h:495
int cs_log_printf_flush(cs_log_t log)
Flush output of a log file.
Definition: cs_log.c:555
Definition: cs_log.h:50
void cs_log_separator(cs_log_t log)
Print a separator line in a log file.
Definition: cs_log.c:591
int cs_log_vprintf(cs_log_t log, const char *format, va_list arg_ptr)
Print log info to a given log type.
Definition: cs_log.c:453
void cs_log_binary_pp_int32(int32_t code, char buf[33])
Pretty-print int-32 based bit field to string.
Definition: cs_log.c:412
Definition: cs_log.h:52
cs_log_t
Definition: cs_log.h:48
void cs_log_default_activate(bool activate)
Update "active" or "inactive" flag of default log.
Definition: cs_log.c:260
bool cs_log_default_is_active(void)
Update "active" or "inactive" flag of default log.
Definition: cs_log.c:277
void cs_log_strpad(char *dest, const char *src, size_t width, size_t destsize)
Pad a string so that its printable length is the required length.
Definition: cs_log.c:366
#define END_C_DECLS
Definition: cs_defs.h:496
int cs_glob_log_frequency
int cs_log_printf(cs_log_t log, const char *format,...)
Print log info to a given log type.
Definition: cs_log.c:501
void cs_log_timer_array_header(cs_log_t log, int indent, const char *header_title, bool calls)
Output timing data array header to a given log.
Definition: cs_log.c:617
void cs_log_strpadl(char *dest, const char *src, size_t width, size_t destsize)
Pad a string on the left so that its printable length is the required length.
Definition: cs_log.c:394
size_t cs_log_strlen(const char *s)
Count printable length of a character string.
Definition: cs_log.c:295
Definition: cs_timer.h:57