programmer's 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-2016 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 
37 /*----------------------------------------------------------------------------*/
38 
40 
41 /*============================================================================
42  * Public types
43  *============================================================================*/
44 
45 /* Code_Saturne log file types */
46 
47 typedef enum {
48 
49  CS_LOG_DEFAULT, /* Default (main) log */
50  CS_LOG_SETUP, /* Calculation setup and options log */
51  CS_LOG_PERFORMANCE, /* Performance log */
52  CS_LOG_N_TYPES /* Number of log file types */
53 
54 } cs_log_t;
55 
56 extern int cs_glob_log_frequency;
57 
58 /*============================================================================
59  * Public macros
60  *============================================================================*/
61 
62 /*============================================================================
63  * Public function prototypes
64  *============================================================================*/
65 
66 /*----------------------------------------------------------------------------
67  * Count printable length of a character string.
68  *
69  * This should also include UTF-8 strings.
70  *
71  * parameters:
72  * str <-- pointer to printable string
73  *
74  * returns:
75  * printable length of character string
76  *----------------------------------------------------------------------------*/
77 
78 size_t
79 cs_log_strlen(const char *s);
80 
81 /*----------------------------------------------------------------------------
82  * Pad a string so that its printable length is the required length.
83  *
84  * This allows pretty-printing with UTF-8 strings, whose actual length may be
85  * larger than their printable length in the presence of multibyte characters.
86  *
87  * If either the printable length of the string is longer than the target
88  * width or the actual length is long than the destination buffer's size,
89  * it is truncated.
90  *
91  * parameters:
92  * dest --> pointer to destination buffer
93  * str <-- pointer to printable string
94  * width <-- desired printed length
95  * destsize <-- destination buffer size
96  *----------------------------------------------------------------------------*/
97 
98 void
99 cs_log_strpad(char *dest,
100  const char *src,
101  size_t width,
102  size_t destsize);
103 
104 /*----------------------------------------------------------------------------
105  * Pad a string on the left so that its printable length is
106  * the required length.
107  *
108  * This allows pretty-printing with UTF-8 strings, whose actual length may be
109  * larger than their printable length in the presence of multibyte characters.
110  *
111  * If either the printable length of the string is longer than the target
112  * width or the actual length is long than the destination buffer's size,
113  * it is truncated.
114  *
115  * parameters:
116  * dest --> pointer to destination buffer
117  * str <-- pointer to printable string
118  * width <-- desired printed length
119  * destsize <-- destination buffer size
120  *----------------------------------------------------------------------------*/
121 
122 void
123 cs_log_strpadl(char *dest,
124  const char *src,
125  size_t width,
126  size_t destsize);
127 
128 /*----------------------------------------------------------------------------*/
144 /*----------------------------------------------------------------------------*/
145 
146 int
148  const char *format,
149  va_list arg_ptr);
150 
151 /*----------------------------------------------------------------------------
152  * Print log info to a given log type.
153  *
154  * The format and variable arguments are similar to those of the printf()
155  * type functions.
156  *
157  * In parallel, output is only handled by rank 0.
158  *
159  * parameters:
160  * format <-- format string, as printf() and family.
161  * ... <-- variable arguments based on format string.
162  *
163  * returns:
164  * number of characters printed, not counting the trailing '\0' used
165  * to end output strings
166  *----------------------------------------------------------------------------*/
167 
168 #if defined(__GNUC__)
169 
170 int
172  const char *format,
173  ...)
174  __attribute__((format(printf, 2, 3)));
175 
176 #else
177 
178 int
180  const char *format,
181  ...);
182 
183 #endif
184 
185 
186 /*----------------------------------------------------------------------------
187  * Flush for output of cs_log_printf() with modifiable behavior.
188  *
189  * If the argument is set to CS_LOG_N_TYPES, all log files are flushed.
190  *
191  * returns:
192  * 0 upon successful completion 0 is returned. Otherwise, EOF is returned
193  * and errno is set to indicate the error.
194  *----------------------------------------------------------------------------*/
195 
196 int
198 
199 /*----------------------------------------------------------------------------
200  * Print a separator line in a log file
201  *
202  * In parallel, output is only handled by rank 0.
203  *
204  * parameters:
205  * log <-- log file type
206  *----------------------------------------------------------------------------*/
207 
208 void
210 
211 /*----------------------------------------------------------------------------
212  * Output timing data block to a given log.
213  *
214  * If the optional array of call counters is used, only lines
215  * with a number of calls greater than 0 are logged.
216  *
217  * In parallel, output is only handled by rank 0.
218  *
219  * parameters:
220  * log <-- log file type
221  * indent <-- indentation before first column
222  * header_title <-- title for optional header line
223  * calls <-- true if calls column is to be used
224  *----------------------------------------------------------------------------*/
225 
226 void
228  int indent,
229  const char *header_title,
230  bool calls);
231 
232 /*----------------------------------------------------------------------------
233  * Output timing data block to a given log.
234  *
235  * If the optional array of call counters is used, only lines
236  * with a number of calls greater than 0 are logged.
237  *
238  * In parallel, output is only handled by rank 0.
239  *
240  * parameters:
241  * log <-- log file type
242  * indent <-- indentation before first column
243  * n_lines <-- number of lines in array, excluding header
244  * line_titles <-- array of titles for data lines
245  * calls <-- optional array of call counters, or NULL
246  * time_count <-- array of time counters
247  *----------------------------------------------------------------------------*/
248 
249 void
251  int indent,
252  int n_lines,
253  const char *line_titles[],
254  const unsigned calls[],
255  const cs_timer_counter_t time_count[]);
256 
257 /*----------------------------------------------------------------------------*/
258 
260 
261 #endif /* __CS_LOG_H__ */
Definition: cs_log.h:50
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:603
Definition: cs_log.h:52
#define BEGIN_C_DECLS
Definition: cs_defs.h:448
int cs_log_printf_flush(cs_log_t log)
Flush output of a log file.
Definition: cs_log.c:485
Definition: cs_log.h:49
void cs_log_separator(cs_log_t log)
Print a separator line in a log file.
Definition: cs_log.c:521
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:383
Definition: cs_log.h:51
cs_log_t
Definition: cs_log.h:47
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:328
#define END_C_DECLS
Definition: cs_defs.h:449
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:431
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:547
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:356
size_t cs_log_strlen(const char *s)
Count printable length of a character string.
Definition: cs_log.c:257
Definition: cs_timer.h:57