programmer's documentation
 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 
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
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
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
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
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
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 
223 
224 #endif /* __CS_LOG_H__ */