src/base/cs_log.h Source File

| programmer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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-2013 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
39 BEGIN_C_DECLS
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
57 /*============================================================================
58 * Public macros
59 *============================================================================*/
60
61 /*============================================================================
62 * Public function prototypes
63 *============================================================================*/
64
65 /*----------------------------------------------------------------------------
66 * Count printable length of a character string.
67 *
68 * This should also include UTF-8 strings.
69 *
70 * parameters:
71 * str <-- pointer to printable string
72 *
73 * returns:
74 * printable length of character string
75 *----------------------------------------------------------------------------*/
76
77 size_t
78 cs_log_strlen(const char *s);
79
80 /*----------------------------------------------------------------------------
81 * Pad a string so that its printable length is the required length.
82 *
83 * This allows pretty-printing with UTF-8 strings, whose actual length may be
84 * larger than their printable length in the presence of multibyte characters.
85 *
86 * If either the printable length of the string is longer than the target
87 * width or the actual length is long than the destination buffer's size,
88 * it is truncated.
89 *
90 * parameters:
91 * dest --> pointer to destination buffer
92 * str <-- pointer to printable string
93 * width <-- desired printed length
94 * destsize <-- destination buffer size
95 *----------------------------------------------------------------------------*/
96
97 void
98 cs_log_strpad(char *dest,
99 const char *src,
100 size_t width,
101 size_t destsize);
102
103 /*----------------------------------------------------------------------------
104 * Pad a string on the left so that its printable length is
105 * the required length.
106 *
107 * This allows pretty-printing with UTF-8 strings, whose actual length may be
108 * larger than their printable length in the presence of multibyte characters.
109 *
110 * If either the printable length of the string is longer than the target
111 * width or the actual length is long than the destination buffer's size,
112 * it is truncated.
113 *
114 * parameters:
115 * dest --> pointer to destination buffer
116 * str <-- pointer to printable string
117 * width <-- desired printed length
118 * destsize <-- destination buffer size
119 *----------------------------------------------------------------------------*/
120
121 void
122 cs_log_strpadl(char *dest,
123 const char *src,
124 size_t width,
125 size_t destsize);
126
127 /*----------------------------------------------------------------------------
128 * Print log info to a given log type.
129 *
130 * The format and variable arguments are similar to those of the printf()
131 * type functions.
132 *
133 * In parallel, output is only handled by rank 0.
134 *
135 * parameters:
136 * format <-- format string, as printf() and family.
137 * ... <-- variable arguments based on format string.
138 *
139 * returns:
140 * number of characters printed, not counting the trailing '\0' used
141 * to end output strings
142 *----------------------------------------------------------------------------*/
143
144 int
145 cs_log_printf(cs_log_t log,
146 const char *format,
147 ...);
148
149 /*----------------------------------------------------------------------------
150 * Flush for output of cs_log_printf() with modifiable behavior.
151 *
152 * If the argument is set to CS_LOG_N_TYPES, all log files are flushed.
153 *
154 * returns:
155 * 0 upon successful completion 0 is returned. Otherwise, EOF is returned
156 * and errno is set to indicate the error.
157 *----------------------------------------------------------------------------*/
158
159 int
160 cs_log_printf_flush(cs_log_t log);
161
162 /*----------------------------------------------------------------------------
163 * Print a separator line in a log file
164 *
165 * In parallel, output is only handled by rank 0.
166 *
167 * parameters:
168 * log <-- log file type
169 *----------------------------------------------------------------------------*/
170
171 void
172 cs_log_separator(cs_log_t log);
173
174 /*----------------------------------------------------------------------------
175 * Output timing data block to a given log.
176 *
177 * If the optional array of call counters is used, only lines
178 * with a number of calls greater than 0 are logged.
179 *
180 * In parallel, output is only handled by rank 0.
181 *
182 * parameters:
183 * log <-- log file type
184 * indent <-- indentation before first column
185 * header_title <-- title for optional header line
186 * calls <-- true if calls column is to be used
187 *----------------------------------------------------------------------------*/
188
189 void
190 cs_log_timer_array_header(cs_log_t log,
191 int indent,
192 const char *header_title,
193 bool calls);
194
195 /*----------------------------------------------------------------------------
196 * Output timing data block to a given log.
197 *
198 * If the optional array of call counters is used, only lines
199 * with a number of calls greater than 0 are logged.
200 *
201 * In parallel, output is only handled by rank 0.
202 *
203 * parameters:
204 * log <-- log file type
205 * indent <-- indentation before first column
206 * n_lines <-- number of lines in array, excluding header
207 * line_titles <-- array of titles for data lines
208 * calls <-- optional array of call counters, or NULL
209 * time_count <-- array of time counters
210 *----------------------------------------------------------------------------*/
211
212 void
213 cs_log_timer_array(cs_log_t log,
214 int indent,
215 int n_lines,
216 const char *line_titles[],
217 const unsigned calls[],
218 const cs_timer_counter_t time_count[]);
219
220 /*----------------------------------------------------------------------------*/
221
222 END_C_DECLS
223
224 #endif /* __CS_LOG_H__ */