8.3
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
48typedef 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
78void
79cs_log_default_activate(bool activate);
80
81/*----------------------------------------------------------------------------*/
90/*----------------------------------------------------------------------------*/
91
92bool
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
107size_t
108cs_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
127void
128cs_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
151void
152cs_log_strpadl(char *dest,
153 const char *src,
154 size_t width,
155 size_t destsize);
156
157/*----------------------------------------------------------------------------*/
164/*----------------------------------------------------------------------------*/
165
166void
167cs_log_binary_pp_int32(int32_t code,
168 char buf[33]);
169
170/*----------------------------------------------------------------------------*/
186/*----------------------------------------------------------------------------*/
187
188int
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
212int
214 const char *format,
215 ...)
216 __attribute__((format(printf, 2, 3)));
217
218#else
219
220int
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
238int
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
250void
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
268void
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
291void
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
317int
318cs_log_warning(const char *format,
319 ...);
320
321/*----------------------------------------------------------------------------*/
322
324
325#endif /* __CS_LOG_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
#define END_C_DECLS
Definition: cs_defs.h:543
int cs_log_printf_flush(cs_log_t log)
Flush output of a log file.
Definition: cs_log.cpp:525
void cs_log_default_activate(bool activate)
Update "active" or "inactive" flag of default log.
Definition: cs_log.cpp:231
bool cs_log_default_is_active(void)
Update "active" or "inactive" flag of default log.
Definition: cs_log.cpp: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.cpp:472
int cs_log_warning(const char *format,...)
Print log info to a given log type.
Definition: cs_log.cpp: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.cpp:365
void cs_log_separator(cs_log_t log)
Print a separator line in a log file.
Definition: cs_log.cpp:561
size_t cs_log_strlen(const char *s)
Count printable length of a character string.
Definition: cs_log.cpp: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.cpp: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.cpp: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.cpp: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.cpp: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.cpp:643
Definition: cs_timer.h:55