doxygen: add newline after \file
[blender.git] / intern / clog / CLG_log.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  */
16
17 #ifndef __CLG_LOG_H__
18 #define __CLG_LOG_H__
19
20 /** \file
21  * \ingroup clog
22  *
23  * C Logging Library (clog)
24  * ========================
25  *
26  * Usage
27  * -----
28  *
29  * - `CLG_LOGREF_DECLARE_GLOBAL` macro to declare #CLG_LogRef pointers.
30  * - `CLOG_` prefixed macros for logging.
31  *
32  * Identifiers
33  * -----------
34  *
35  * #CLG_LogRef holds an identifier which defines the category of the logger.
36  *
37  * You can define and use identifiers as needed, logging will lazily initialize them.
38  *
39  * By convention lower case dot separated identifiers are used, eg:
40  * `module.sub_module`, this allows filtering by `module.*`,
41  * see #CLG_type_filter_include, #CLG_type_filter_exclude
42  *
43  * There is currently no functionality to remove a category once it's created.
44  *
45  * Severity
46  * --------
47  *
48  * - `INFO`: Simply log events, uses verbosity levels to control how much information to show.
49  * - `WARN`: General warnings (which aren't necessary to show to users).
50  * - `ERROR`: An error we can recover from, should not happen.
51  * - `FATAL`: Similar to assert. This logs the message, then a stack trace and abort.
52  * Verbosity Level
53  * ---------------
54  *
55  * Usage:
56  *
57  * - 0: Always show (used for warnings, errors).
58  *   Should never get in the way or become annoying.
59  *
60  * - 1: Top level module actions (eg: load a file, create a new window .. etc).
61  *
62  * - 2: Actions within a module (steps which compose an action, but don't flood output).
63  *   Running a tool, full data recalculation.
64  *
65  * - 3: Detailed actions which may be of interest when debugging internal logic of a module
66  *   These *may* flood the log with details.
67  *
68  * - 4+: May be used for more details than 3, should be avoided but not prevented.
69  */
70
71 #ifdef __cplusplus
72 extern "C" {
73 #endif /* __cplusplus */
74
75 #ifdef __GNUC__
76 #  define _CLOG_ATTR_NONNULL(args ...) __attribute__((nonnull(args)))
77 #else
78 #  define _CLOG_ATTR_NONNULL(...)
79 #endif
80
81 #ifdef __GNUC__
82 #  define _CLOG_ATTR_PRINTF_FORMAT(format_param, dots_param) __attribute__((format(printf, format_param, dots_param)))
83 #else
84 #  define _CLOG_ATTR_PRINTF_FORMAT(format_param, dots_param)
85 #endif
86
87 #define STRINGIFY_ARG(x) "" #x
88 #define STRINGIFY_APPEND(a, b) "" a #b
89 #define STRINGIFY(x) STRINGIFY_APPEND("", x)
90
91 struct CLogContext;
92
93 /* Don't typedef enums. */
94 enum CLG_LogFlag {
95         CLG_FLAG_USE = (1 << 0),
96 };
97
98 enum CLG_Severity {
99         CLG_SEVERITY_INFO = 0,
100         CLG_SEVERITY_WARN,
101         CLG_SEVERITY_ERROR,
102         CLG_SEVERITY_FATAL,
103 };
104 #define CLG_SEVERITY_LEN (CLG_SEVERITY_FATAL + 1)
105
106 /* Each logger ID has one of these. */
107 typedef struct CLG_LogType {
108         struct CLG_LogType *next;
109         char identifier[64];
110         /** FILE output. */
111         struct CLogContext *ctx;
112         /** Control behavior. */
113         int level;
114         enum CLG_LogFlag flag;
115 } CLG_LogType;
116
117 typedef struct CLG_LogRef {
118         const char *identifier;
119         CLG_LogType *type;
120 } CLG_LogRef;
121
122 void CLG_log_str(
123         CLG_LogType *lg, enum CLG_Severity severity, const char *file_line, const char *fn,
124         const char *message)
125         _CLOG_ATTR_NONNULL(1, 3, 4, 5);
126 void CLG_logf(
127         CLG_LogType *lg, enum CLG_Severity severity, const char *file_line, const char *fn,
128         const char *format, ...)
129         _CLOG_ATTR_NONNULL(1, 3, 4, 5) _CLOG_ATTR_PRINTF_FORMAT(5, 6);
130
131 /* Main initializer and distructor (per session, not logger). */
132 void CLG_init(void);
133 void CLG_exit(void);
134
135 void CLG_output_set(void *file_handle);
136 void CLG_output_use_basename_set(int value);
137 void CLG_output_use_timestamp_set(int value);
138 void CLG_fatal_fn_set(void (*fatal_fn)(void *file_handle));
139 void CLG_backtrace_fn_set(void (*fatal_fn)(void *file_handle));
140
141 void CLG_type_filter_include(const char *type_filter, int type_filter_len);
142 void CLG_type_filter_exclude(const char *type_filter, int type_filter_len);
143
144 void CLG_level_set(int level);
145
146 void CLG_logref_init(CLG_LogRef *clg_ref);
147
148 /** Declare outside function, declare as extern in header. */
149 #define CLG_LOGREF_DECLARE_GLOBAL(var, id) \
150         static CLG_LogRef _static_ ## var = {id}; \
151         CLG_LogRef *var = &_static_ ## var
152
153 /** Initialize struct once. */
154 #define CLOG_ENSURE(clg_ref) \
155         ((clg_ref)->type ? (clg_ref)->type : (CLG_logref_init(clg_ref), (clg_ref)->type))
156
157 #define CLOG_AT_SEVERITY(clg_ref, severity, verbose_level, ...) { \
158         CLG_LogType *_lg_ty = CLOG_ENSURE(clg_ref); \
159         if (((_lg_ty->flag & CLG_FLAG_USE) && (_lg_ty->level >= verbose_level)) || (severity >= CLG_SEVERITY_WARN)) { \
160                 CLG_logf(_lg_ty, severity, __FILE__ ":" STRINGIFY(__LINE__), __func__, __VA_ARGS__); \
161         } \
162 } ((void)0)
163
164 #define CLOG_STR_AT_SEVERITY(clg_ref, severity, verbose_level, str) { \
165         CLG_LogType *_lg_ty = CLOG_ENSURE(clg_ref); \
166         if (((_lg_ty->flag & CLG_FLAG_USE) && (_lg_ty->level >= verbose_level)) || (severity >= CLG_SEVERITY_WARN)) { \
167                 CLG_log_str(_lg_ty, severity, __FILE__ ":" STRINGIFY(__LINE__), __func__, str); \
168         } \
169 } ((void)0)
170
171 #define CLOG_STR_AT_SEVERITY_N(clg_ref, severity, verbose_level, str) { \
172         CLG_LogType *_lg_ty = CLOG_ENSURE(clg_ref); \
173         if (((_lg_ty->flag & CLG_FLAG_USE) && (_lg_ty->level >= verbose_level)) || (severity >= CLG_SEVERITY_WARN)) { \
174                 const char *_str = str; \
175                 CLG_log_str(_lg_ty, severity, __FILE__ ":" STRINGIFY(__LINE__), __func__, _str); \
176                 MEM_freeN((void *)_str); \
177         } \
178 } ((void)0)
179
180 #define CLOG_INFO(clg_ref, level, ...) CLOG_AT_SEVERITY(clg_ref, CLG_SEVERITY_INFO, level, __VA_ARGS__)
181 #define CLOG_WARN(clg_ref, ...)        CLOG_AT_SEVERITY(clg_ref, CLG_SEVERITY_WARN, 0, __VA_ARGS__)
182 #define CLOG_ERROR(clg_ref, ...)       CLOG_AT_SEVERITY(clg_ref, CLG_SEVERITY_ERROR, 0, __VA_ARGS__)
183 #define CLOG_FATAL(clg_ref, ...)       CLOG_AT_SEVERITY(clg_ref, CLG_SEVERITY_FATAL, 0, __VA_ARGS__)
184
185 #define CLOG_STR_INFO(clg_ref, level, str) CLOG_STR_AT_SEVERITY(clg_ref, CLG_SEVERITY_INFO, level, str)
186 #define CLOG_STR_WARN(clg_ref, str)        CLOG_STR_AT_SEVERITY(clg_ref, CLG_SEVERITY_WARN, 0, str)
187 #define CLOG_STR_ERROR(clg_ref, str)       CLOG_STR_AT_SEVERITY(clg_ref, CLG_SEVERITY_ERROR, 0, str)
188 #define CLOG_STR_FATAL(clg_ref, str)       CLOG_STR_AT_SEVERITY(clg_ref, CLG_SEVERITY_FATAL, 0, str)
189
190 /* Allocated string which is immediately freed. */
191 #define CLOG_STR_INFO_N(clg_ref, level, str) CLOG_STR_AT_SEVERITY_N(clg_ref, CLG_SEVERITY_INFO, level, str)
192 #define CLOG_STR_WARN_N(clg_ref, str)        CLOG_STR_AT_SEVERITY_N(clg_ref, CLG_SEVERITY_WARN, 0, str)
193 #define CLOG_STR_ERROR_N(clg_ref, str)       CLOG_STR_AT_SEVERITY_N(clg_ref, CLG_SEVERITY_ERROR, 0, str)
194 #define CLOG_STR_FATAL_N(clg_ref, str)       CLOG_STR_AT_SEVERITY_N(clg_ref, CLG_SEVERITY_FATAL, 0, str)
195
196 #ifdef __cplusplus
197 }
198 #endif
199
200 #endif /* __CLG_LOG_H__ */