8.2
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-2024 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_WARNINGS, /* Warnings log */
54  CS_LOG_N_TYPES /* Number of log file types */
55 
57 
58 /*============================================================================
59  * Public macros
60  *============================================================================*/
61 
62 /*============================================================================
63  * Public function prototypes
64  *============================================================================*/
65 
66 /*----------------------------------------------------------------------------*/
76 /*----------------------------------------------------------------------------*/
77 
78 void
79 cs_log_default_activate(bool activate);
80 
81 /*----------------------------------------------------------------------------*/
90 /*----------------------------------------------------------------------------*/
91 
92 bool
94 
95 /*----------------------------------------------------------------------------
96  * Count printable length of a character string.
97  *
98  * This should also include UTF-8 strings.
99  *
100  * parameters:
101  * str <-- pointer to printable string
102  *
103  * returns:
104  * printable length of character string
105  *----------------------------------------------------------------------------*/
106 
107 size_t
108 cs_log_strlen(const char *s);
109 
110 /*----------------------------------------------------------------------------
111  * Pad a string so that its printable length is the required length.
112  *
113  * This allows pretty-printing with UTF-8 strings, whose actual length may be
114  * larger than their printable length in the presence of multibyte characters.
115  *
116  * If either the printable length of the string is longer than the target
117  * width or the actual length is long than the destination buffer's size,
118  * it is truncated.
119  *
120  * parameters:
121  * dest --> pointer to destination buffer
122  * str <-- pointer to printable string
123  * width <-- desired printed length
124  * destsize <-- destination buffer size
125  *----------------------------------------------------------------------------*/
126 
127 void
128 cs_log_strpad(char *dest,
129  const char *src,
130  size_t width,
131  size_t destsize);
132 
133 /*----------------------------------------------------------------------------
134  * Pad a string on the left so that its printable length is
135  * the required length.
136  *
137  * This allows pretty-printing with UTF-8 strings, whose actual length may be
138  * larger than their printable length in the presence of multibyte characters.
139  *
140  * If either the printable length of the string is longer than the target
141  * width or the actual length is long than the destination buffer's size,
142  * it is truncated.
143  *
144  * parameters:
145  * dest --> pointer to destination buffer
146  * str <-- pointer to printable string
147  * width <-- desired printed length
148  * destsize <-- destination buffer size
149  *----------------------------------------------------------------------------*/
150 
151 void
152 cs_log_strpadl(char *dest,
153  const char *src,
154  size_t width,
155  size_t destsize);
156 
157 /*----------------------------------------------------------------------------*/
164 /*----------------------------------------------------------------------------*/
165 
166 void
167 cs_log_binary_pp_int32(int32_t code,
168  char buf[33]);
169 
170 /*----------------------------------------------------------------------------*/
186 /*----------------------------------------------------------------------------*/
187 
188 int
190  const char *format,
191  va_list arg_ptr);
192 
193 /*----------------------------------------------------------------------------
194  * Print log info to a given log type.
195  *
196  * The format and variable arguments are similar to those of the printf()
197  * type functions.
198  *
199  * In parallel, output is only handled by rank 0.
200  *
201  * parameters:
202  * format <-- format string, as printf() and family.
203  * ... <-- variable arguments based on format string.
204  *
205  * returns:
206  * number of characters printed, not counting the trailing '\0' used
207  * to end output strings
208  *----------------------------------------------------------------------------*/
209 
210 #if defined(__GNUC__)
211 
212 int
214  const char *format,
215  ...)
216  __attribute__((format(printf, 2, 3)));
217 
218 #else
219 
220 int
222  const char *format,
223  ...);
224 
225 #endif
226 
227 
228 /*----------------------------------------------------------------------------
229  * Flush for output of cs_log_printf() with modifiable behavior.
230  *
231  * If the argument is set to CS_LOG_N_TYPES, all log files are flushed.
232  *
233  * returns:
234  * 0 upon successful completion 0 is returned. Otherwise, EOF is returned
235  * and errno is set to indicate the error.
236  *----------------------------------------------------------------------------*/
237 
238 int
240 
241 /*----------------------------------------------------------------------------
242  * Print a separator line in a log file
243  *
244  * In parallel, output is only handled by rank 0.
245  *
246  * parameters:
247  * log <-- log file type
248  *----------------------------------------------------------------------------*/
249 
250 void
252 
253 /*----------------------------------------------------------------------------
254  * Output timing data block to a given log.
255  *
256  * If the optional array of call counters is used, only lines
257  * with a number of calls greater than 0 are logged.
258  *
259  * In parallel, output is only handled by rank 0.
260  *
261  * parameters:
262  * log <-- log file type
263  * indent <-- indentation before first column
264  * header_title <-- title for optional header line
265  * calls <-- true if calls column is to be used
266  *----------------------------------------------------------------------------*/
267 
268 void
270  int indent,
271  const char *header_title,
272  bool calls);
273 
274 /*----------------------------------------------------------------------------
275  * Output timing data block to a given log.
276  *
277  * If the optional array of call counters is used, only lines
278  * with a number of calls greater than 0 are logged.
279  *
280  * In parallel, output is only handled by rank 0.
281  *
282  * parameters:
283  * log <-- log file type
284  * indent <-- indentation before first column
285  * n_lines <-- number of lines in array, excluding header
286  * line_titles <-- array of titles for data lines
287  * calls <-- optional array of call counters, or NULL
288  * time_count <-- array of time counters
289  *----------------------------------------------------------------------------*/
290 
291 void
293  int indent,
294  int n_lines,
295  const char *line_titles[],
296  const unsigned calls[],
297  const cs_timer_counter_t time_count[]);
298 
299 /*----------------------------------------------------------------------------*/
315 /*----------------------------------------------------------------------------*/
316 
317 int
318 cs_log_warning(const char *format,
319  ...);
320 
321 /*----------------------------------------------------------------------------*/
322 
324 
325 #endif /* __CS_LOG_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:528
#define END_C_DECLS
Definition: cs_defs.h:529
int cs_log_printf_flush(cs_log_t log)
Flush output of a log file.
Definition: cs_log.c:525
void cs_log_default_activate(bool activate)
Update "active" or "inactive" flag of default log.
Definition: cs_log.c:231
bool cs_log_default_is_active(void)
Update "active" or "inactive" flag of default log.
Definition: cs_log.c:248
cs_log_t
Definition: cs_log.h:48
@ CS_LOG_DEFAULT
Definition: cs_log.h:50
@ CS_LOG_WARNINGS
Definition: cs_log.h:53
@ CS_LOG_PERFORMANCE
Definition: cs_log.h:52
@ CS_LOG_N_TYPES
Definition: cs_log.h:54
@ CS_LOG_SETUP
Definition: cs_log.h:51
int cs_log_printf(cs_log_t log, const char *format,...)
Print log info to a given log type.
Definition: cs_log.c:472
int cs_log_warning(const char *format,...)
Print log info to a given log type.
Definition: cs_log.c:699
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:365
void cs_log_separator(cs_log_t log)
Print a separator line in a log file.
Definition: cs_log.c:561
size_t cs_log_strlen(const char *s)
Count printable length of a character string.
Definition: cs_log.c:266
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:337
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:383
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:424
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:587
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:643
Definition: cs_timer.h:55