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