Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Remove old style logging macros.
[simgrid.git] / include / xbt / log.h
1 /* log - a generic logging facility in the spirit of log4j                  */
2
3 /* Copyright (c) 2004, 2005, 2006, 2007, 2008, 2009, 2010. The SimGrid Team.
4  * All rights reserved.                                                     */
5
6 /* This program is free software; you can redistribute it and/or modify it
7  * under the terms of the license (GNU LGPL) which comes with this package. */
8
9 /** @addtogroup XBT_log
10  *  @brief A generic logging facility in the spirit of log4j (grounding feature)
11  *
12  *
13  */
14
15 /** \defgroup XBT_log_cats Existing log categories
16  *  \ingroup XBT_log
17  *  \brief (automatically extracted) 
18  *     
19  *  This is the list of all existing log categories in SimGrid.
20  *  This list was automatically extracted from the source code by
21  *  the src/xbt_log_extract_hierarchy utility.
22  *     
23  *  You can thus be certain that it is uptodate, but it may somehow
24  *  lack a final manual touch.
25  *  Anyway, nothing's perfect ;)
26  */
27
28 /* XBT_LOG_MAYDAY: define this to replace the logging facilities with basic
29    printf function. Useful to debug the logging facilities themselves */
30 #undef XBT_LOG_MAYDAY
31 //#define XBT_LOG_MAYDAY
32
33 #ifndef _XBT_LOG_H_
34 #define _XBT_LOG_H_
35
36 #include "xbt/misc.h"
37 #include <stdarg.h>
38 SG_BEGIN_DECL()
39 /**\brief Log priorities
40  * \ingroup XBT_log
41  *
42  * The different existing priorities.
43 */
44 typedef enum {
45   xbt_log_priority_none = 0,    /* used internally (don't poke with) */
46   xbt_log_priority_trace = 1,          /**< enter and return of some functions */
47   xbt_log_priority_debug = 2,          /**< crufty output  */
48   xbt_log_priority_verbose = 3,        /**< verbose output for the user wanting more */
49   xbt_log_priority_info = 4,           /**< output about the regular functionning */
50   xbt_log_priority_warning = 5,        /**< minor issue encountered */
51   xbt_log_priority_error = 6,          /**< issue encountered */
52   xbt_log_priority_critical = 7,       /**< major issue encountered */
53
54   xbt_log_priority_infinite = 8,       /**< value for XBT_LOG_STATIC_THRESHOLD to not log */
55
56   xbt_log_priority_uninitialized = -1   /* used internally (don't poke with) */
57 } e_xbt_log_priority_t;
58
59
60 /*
61  * define NLOG to disable at compilation time any logging request
62  * define NDEBUG to disable at compilation time any logging request of priority below INFO
63  */
64
65
66 /**
67  * @def XBT_LOG_STATIC_THRESHOLD
68  * @ingroup XBT_log
69  *
70  * All logging requests with priority < XBT_LOG_STATIC_THRESHOLD are disabled at
71  * compile time, i.e., compiled out.
72  */
73 #ifdef NLOG
74 #  define XBT_LOG_STATIC_THRESHOLD xbt_log_priority_infinite
75 #else
76
77 #  ifdef NDEBUG
78 #    define XBT_LOG_STATIC_THRESHOLD xbt_log_priority_verbose
79 #  else                         /* !NLOG && !NDEBUG */
80
81 #    ifndef XBT_LOG_STATIC_THRESHOLD
82 #      define XBT_LOG_STATIC_THRESHOLD xbt_log_priority_none
83 #    endif                      /* !XBT_LOG_STATIC_THRESHOLD */
84 #  endif                        /* NDEBUG */
85 #endif                          /* !defined(NLOG) */
86
87 /* Transforms a category name to a global variable name. */
88 #define _XBT_LOGV(cat)   _XBT_LOG_CONCAT(_simgrid_log_category__, cat)
89 #define _XBT_LOG_CONCAT(x,y) x ## y
90
91 /* The root of the category hierarchy. */
92 #define XBT_LOG_ROOT_CAT   root
93
94 /* The whole tree of categories is connected by setting the address of
95  * the parent category as a field of the child one.
96  *
97  * In strict ansi C, we are allowed to initialize a variable with "a
98  * pointer to an lvalue designating an object of static storage
99  * duration" [ISO/IEC 9899:1999, Section 6.6].
100  * 
101  * Unfortunately, Visual C builder does not target any standard
102  * compliance, and C99 is not an exception to this unfortunate rule.
103  * 
104  * So, we work this around by adding a XBT_LOG_CONNECT() macro,
105  * allowing to connect a child to its parent. It should be used
106  * during the initialization of the code, before the child category
107  * gets used.
108  * 
109  * When compiling with gcc, this is not necessary (XBT_LOG_CONNECT
110  * defines to nothing). When compiling with MSVC, this is needed if
111  * you don't want to see your child category become a child of root
112  * directly.
113  */
114 #if defined(_MSC_VER)
115 # define _XBT_LOG_PARENT_INITIALIZER(parent) NULL
116 # define XBT_LOG_CONNECT(parent_cat,child)       _XBT_LOGV(child).parent = &_XBT_LOGV(parent_cat)
117 #else
118 # define _XBT_LOG_PARENT_INITIALIZER(parent) &_XBT_LOGV(parent)
119 # define XBT_LOG_CONNECT(parent_cat,child)      /*  xbt_assert(_XBT_LOGV(child).parent == &_XBT_LOGV(parent_cat)) */
120 #endif
121
122 /* XBT_LOG_NEW_SUBCATEGORY_helper:
123  * Implementation of XBT_LOG_NEW_SUBCATEGORY, which must declare "extern parent" in addition
124  * to avoid an extra declaration of root when XBT_LOG_NEW_SUBCATEGORY is called by
125  * XBT_LOG_NEW_CATEGORY */
126 #define XBT_LOG_NEW_SUBCATEGORY_helper(catName, parent, desc) \
127     XBT_EXPORT_NO_IMPORT(s_xbt_log_category_t) _XBT_LOGV(catName) = {       \
128         _XBT_LOG_PARENT_INITIALIZER(parent),            \
129         NULL /* firstChild */,                          \
130         NULL /* nextSibling */,                         \
131         #catName,                                       \
132         xbt_log_priority_uninitialized /* threshold */, \
133         1 /* isThreshInherited */,                      \
134         NULL /* appender */,                            \
135         NULL /* layout */,                              \
136         1 /* additivity */                              \
137     }
138 /**
139  * \ingroup XBT_log
140  * \param catName name of new category
141  * \param parent father of the new category in the tree
142  * \param desc string describing the purpose of this category
143  * \hideinitializer
144  *
145  * Defines a new subcategory of the parent. 
146  */
147 #define XBT_LOG_NEW_SUBCATEGORY(catName, parent, desc)    \
148     extern s_xbt_log_category_t _XBT_LOGV(parent); \
149     XBT_LOG_NEW_SUBCATEGORY_helper(catName, parent, desc) \
150
151 /**
152  * \ingroup XBT_log  
153  * \param catName name of new category
154  * \param desc string describing the purpose of this category
155  * \hideinitializer
156  *
157  * Creates a new subcategory of the root category.
158  */
159 # define XBT_LOG_NEW_CATEGORY(catName,desc)  \
160    XBT_LOG_NEW_SUBCATEGORY_helper(catName, XBT_LOG_ROOT_CAT, desc)
161
162
163 /**
164  * \ingroup XBT_log  
165  * \param cname name of the cat
166  * \hideinitializer
167  *
168  * Indicates which category is the default one.
169  */
170
171 #if defined(XBT_LOG_MAYDAY) || defined(SUPERNOVAE_MODE) /*|| defined (NLOG) * turning logging off */
172 # define XBT_LOG_DEFAULT_CATEGORY(cname)
173 #else
174 # define XBT_LOG_DEFAULT_CATEGORY(cname) \
175          static xbt_log_category_t _XBT_LOGV(default) _XBT_GNUC_UNUSED = &_XBT_LOGV(cname)
176 #endif
177
178 /**
179  * \ingroup XBT_log  
180  * \param cname name of the cat
181  * \param desc string describing the purpose of this category
182  * \hideinitializer
183  *
184  * Creates a new subcategory of the root category and makes it the default
185  * (used by macros that don't explicitly specify a category).
186  */
187 # define XBT_LOG_NEW_DEFAULT_CATEGORY(cname,desc)        \
188     XBT_LOG_NEW_CATEGORY(cname,desc);                   \
189     XBT_LOG_DEFAULT_CATEGORY(cname)
190
191 /**
192  * \ingroup XBT_log  
193  * \param cname name of the cat
194  * \param parent name of the parent
195  * \param desc string describing the purpose of this category
196  * \hideinitializer
197  *
198  * Creates a new subcategory of the parent category and makes it the default
199  * (used by macros that don't explicitly specify a category).
200  */
201 #define XBT_LOG_NEW_DEFAULT_SUBCATEGORY(cname, parent, desc) \
202     XBT_LOG_NEW_SUBCATEGORY(cname, parent, desc);            \
203     XBT_LOG_DEFAULT_CATEGORY(cname)
204
205 /**
206  * \ingroup XBT_log  
207  * \param cname name of the cat
208  * \hideinitializer
209  *
210  * Indicates that a category you'll use in this file (to get subcategories of it, 
211  * for example) really lives in another file.
212  */
213
214 #define XBT_LOG_EXTERNAL_CATEGORY(cname) \
215    extern s_xbt_log_category_t _XBT_LOGV(cname)
216
217 /**
218  * \ingroup XBT_log
219  * \param cname name of the cat
220  * \hideinitializer
221  *
222  * Indicates that the default category of this file was declared in another file.
223  */
224
225 #define XBT_LOG_EXTERNAL_DEFAULT_CATEGORY(cname) \
226    XBT_LOG_EXTERNAL_CATEGORY(cname);\
227    XBT_LOG_DEFAULT_CATEGORY(cname)
228
229 /* Functions you may call */
230
231 XBT_PUBLIC(void) xbt_log_control_set(const char *cs);
232
233 /* Forward declarations */
234 typedef struct xbt_log_appender_s s_xbt_log_appender_t,
235     *xbt_log_appender_t;
236 typedef struct xbt_log_layout_s s_xbt_log_layout_t, *xbt_log_layout_t;
237 typedef struct xbt_log_event_s s_xbt_log_event_t, *xbt_log_event_t;
238 typedef struct xbt_log_category_s s_xbt_log_category_t,
239     *xbt_log_category_t;
240
241 /*
242  * Do NOT access any members of this structure directly. FIXME: move to private?
243  */
244 #ifdef _XBT_WIN32
245 #define XBT_LOG_BUFF_SIZE  16384        /* Size of the static string in which we build the log string */
246 #else
247 #define XBT_LOG_BUFF_SIZE 2048  /* Size of the static string in which we build the log string */
248 #endif
249 struct xbt_log_category_s {
250   xbt_log_category_t parent;
251   xbt_log_category_t firstChild;
252   xbt_log_category_t nextSibling;
253   const char *name;
254   int threshold;
255   int isThreshInherited;
256   xbt_log_appender_t appender;
257   xbt_log_layout_t layout;
258   int additivity;
259 };
260
261 struct xbt_log_event_s {
262   xbt_log_category_t cat;
263   e_xbt_log_priority_t priority;
264   const char *fileName;
265   const char *functionName;
266   int lineNum;
267   va_list ap;
268   va_list ap_copy;              /* need a copy to launch dynamic layouts when the static ones overflowed */
269 #ifdef _XBT_WIN32
270   char *buffer;
271 #else
272   char buffer[XBT_LOG_BUFF_SIZE];
273 #endif
274 };
275
276 /**
277  * \ingroup XBT_log_implem
278  * \param cat the category (not only its name, but the variable)
279  * \param thresholdPriority the priority
280  *
281  * Programatically alters a category's threshold priority (don't use).
282  */
283 XBT_PUBLIC(void) xbt_log_threshold_set(xbt_log_category_t cat,
284                                        e_xbt_log_priority_t
285                                        thresholdPriority);
286
287 /**
288  * \ingroup XBT_log_implem  
289  * \param cat the category (not only its name, but the variable)
290  * \param app the appender
291  *
292  * Programatically sets the category's appender.
293  * (the prefered interface is throught xbt_log_control_set())
294  *
295  */
296 XBT_PUBLIC(void) xbt_log_appender_set(xbt_log_category_t cat,
297                                       xbt_log_appender_t app);
298 /**
299  * \ingroup XBT_log_implem  
300  * \param cat the category (not only its name, but the variable)
301  * \param lay the layout
302  *
303  * Programatically sets the category's layout.
304  * (the prefered interface is throught xbt_log_control_set())
305  *
306  */
307 XBT_PUBLIC(void) xbt_log_layout_set(xbt_log_category_t cat,
308                                     xbt_log_layout_t lay);
309
310 /**
311  * \ingroup XBT_log_implem  
312  * \param cat the category (not only its name, but the variable)
313  * \param additivity whether logging actions must be passed to parent.
314  *
315  * Programatically sets whether the logging actions must be passed to 
316  * the parent category.
317  * (the prefered interface is throught xbt_log_control_set())
318  *
319  */
320 XBT_PUBLIC(void) xbt_log_additivity_set(xbt_log_category_t cat,
321                                         int additivity);
322
323 /** @brief create a new simple layout 
324  *
325  * This layout is not as flexible as the pattern one
326  */
327 XBT_PUBLIC(xbt_log_layout_t) xbt_log_layout_simple_new(char *arg);
328 XBT_PUBLIC(xbt_log_layout_t) xbt_log_layout_format_new(char *arg);
329 XBT_PUBLIC(xbt_log_appender_t) xbt_log_appender_file_new(char *arg);
330
331
332 /* ********************************** */
333 /* Functions that you shouldn't call  */
334 /* ********************************** */
335 XBT_PUBLIC(void) _xbt_log_event_log(xbt_log_event_t ev,
336                                     const char *fmt,
337                                     ...) _XBT_GNUC_PRINTF(2, 3);
338
339 XBT_PUBLIC(int) _xbt_log_cat_init(xbt_log_category_t category,
340                                   e_xbt_log_priority_t priority);
341
342
343 XBT_PUBLIC_DATA(s_xbt_log_category_t) _XBT_LOGV(XBT_LOG_ROOT_CAT);
344
345
346 extern xbt_log_appender_t xbt_log_default_appender;
347 extern xbt_log_layout_t xbt_log_default_layout;
348
349 /* ********************** */
350 /* Public functions again */
351 /* ********************** */
352
353 /**
354  * \ingroup XBT_log 
355  * \param catName name of the category
356  * \param priority minimal priority to be enabled to return true (must be #e_xbt_log_priority_t)
357  * \hideinitializer
358  *
359  * Returns true if the given priority is enabled for the category.
360  * If you have expensive expressions that are computed outside of the log
361  * command and used only within it, you should make its evaluation conditional
362  * using this macro.
363  */
364 #define XBT_LOG_ISENABLED(catName, priority) \
365             _XBT_LOG_ISENABLEDV(_XBT_LOGV(catName), priority)
366
367 /*
368  * Helper function that implements XBT_LOG_ISENABLED.
369  *
370  * NOTES
371  * First part is a compile-time constant.
372  * Call to _log_initCat only happens once.
373  */
374 #define _XBT_LOG_ISENABLEDV(catv, priority)                  \
375        (priority >= XBT_LOG_STATIC_THRESHOLD                 \
376         && priority >= catv.threshold                         \
377         && (catv.threshold != xbt_log_priority_uninitialized \
378             || _xbt_log_cat_init(&catv, priority)) )
379
380 /*
381  * Internal Macros
382  * Some kludge macros to ease maintenance. See how they're used below.
383  *
384  * IMPLEMENTATION NOTE: To reduce the parameter passing overhead of an enabled
385  * message, the many parameters passed to the logging function are packed in a
386  * structure. Since these values will be usually be passed to at least 3
387  * functions, this is a win.
388  * It also allows adding new values (such as a timestamp) without breaking
389  * code. 
390  * Setting the LogEvent's valist member is done inside _log_logEvent.
391  */
392 #ifdef _XBT_WIN32
393 #include <stdlib.h>             /* calloc */
394 #define _XBT_LOG_EV_BUFFER_ZERO() \
395   _log_ev.buffer = (char*) calloc(XBT_LOG_BUFF_SIZE + 1, sizeof(char))
396 #else
397 #include <string.h>             /* memset */
398 #define _XBT_LOG_EV_BUFFER_ZERO() \
399   memset(_log_ev.buffer, 0, XBT_LOG_BUFF_SIZE)
400 #endif
401
402 /* Logging Macros */
403
404 #ifdef XBT_LOG_MAYDAY
405 # define XBT_CLOG_(cat, prio, f, ...) \
406   fprintf(stderr,"%s:%d:" f "%c", __FILE__, __LINE__, __VA_ARGS__)
407 # define XBT_CLOG(cat, prio, ...) XBT_CLOG_(cat, prio, __VA_ARGS__, '\n')
408 # define XBT_LOG(...) XBT_CLOG(0, __VA_ARGS__)
409 #else
410 # define XBT_CLOG_(catv, prio, ...)                                     \
411   do {                                                                  \
412     if (_XBT_LOG_ISENABLEDV(catv, prio)) {                              \
413       s_xbt_log_event_t _log_ev;                                        \
414       _log_ev.cat = &(catv);                                            \
415       _log_ev.priority = (prio);                                        \
416       _log_ev.fileName = __FILE__;                                      \
417       _log_ev.functionName = _XBT_FUNCTION;                             \
418       _log_ev.lineNum = __LINE__;                                       \
419       _XBT_LOG_EV_BUFFER_ZERO();                                        \
420       _xbt_log_event_log(&_log_ev, __VA_ARGS__);                        \
421     }                                                                   \
422   }  while (0)
423 # define XBT_CLOG(cat, prio, ...) XBT_CLOG_(_XBT_LOGV(cat), prio, __VA_ARGS__)
424 # define XBT_LOG(...) XBT_CLOG_((*_XBT_LOGV(default)), __VA_ARGS__)
425 #endif
426
427 /** @ingroup XBT_log
428  *  @hideinitializer
429  * \param c the category on which to log
430  * \param f the format string
431  * \param ... arguments of the format
432  *  @brief Log an event at the DEBUG priority on the specified category with these args.
433  */
434 #define XBT_CDEBUG(c, ...) XBT_CLOG(c, xbt_log_priority_debug, __VA_ARGS__)
435
436 /** @ingroup XBT_log
437  *  @hideinitializer
438  *  @brief Log an event at the VERB priority on the specified category with these args.
439  */
440 #define XBT_CVERB(c, ...) XBT_CLOG(c, xbt_log_priority_verbose, __VA_ARGS__)
441
442 /** @ingroup XBT_log
443  *  @hideinitializer
444  *  @brief Log an event at the INFO priority on the specified category with these args.
445  */
446 #define XBT_CINFO(c, ...) XBT_CLOG(c, xbt_log_priority_info, __VA_ARGS__)
447
448 /** @ingroup XBT_log
449  *  @hideinitializer
450  *  @brief Log an event at the WARN priority on the specified category with these args.
451  */
452 #define XBT_CWARN(c, ...) XBT_CLOG(c, xbt_log_priority_warning, __VA_ARGS__)
453
454 /** @ingroup XBT_log
455  *  @hideinitializer
456  *  @brief Log an event at the ERROR priority on the specified category with these args.
457  */
458 #define XBT_CERROR(c, ...) XBT_CLOG(c, xbt_log_priority_error, __VA_ARGS__)
459
460 /** @ingroup XBT_log
461  *  @hideinitializer
462  *  @brief Log an event at the CRITICAL priority on the specified category with these args (CCRITICALn exists for any n<10).
463  */
464 #define XBT_CCRITICAL(c, ...) XBT_CLOG(c, xbt_log_priority_critical, __VA_ARGS__)
465
466 /** @ingroup XBT_log
467  *  @hideinitializer
468  * \param f the format string
469  * \param ...
470  *  @brief Log an event at the DEBUG priority on the default category with these args.
471  */
472 #define XBT_DEBUG(...) XBT_LOG(xbt_log_priority_debug, __VA_ARGS__)
473
474 /** @ingroup XBT_log
475  *  @hideinitializer
476  *  @brief Log an event at the VERB priority on the default category with these args.
477  */
478 #define XBT_VERB(...) XBT_LOG(xbt_log_priority_verbose, __VA_ARGS__)
479
480 /** @ingroup XBT_log
481  *  @hideinitializer
482  *  @brief Log an event at the INFO priority on the default category with these args.
483  */
484 #define XBT_INFO(...) XBT_LOG(xbt_log_priority_info, __VA_ARGS__)
485
486 /** @ingroup XBT_log
487  *  @hideinitializer
488  *  @brief Log an event at the WARN priority on the default category with these args.
489  */
490 #define XBT_WARN(...) XBT_LOG(xbt_log_priority_warning, __VA_ARGS__)
491
492 /** @ingroup XBT_log
493  *  @hideinitializer
494  *  @brief Log an event at the ERROR priority on the default category with these args.
495  */
496 #define XBT_ERROR(...) XBT_LOG(xbt_log_priority_error, __VA_ARGS__)
497
498 /** @ingroup XBT_log
499  *  @hideinitializer
500  *  @brief Log an event at the CRITICAL priority on the default category with these args.
501  */
502 #define XBT_CRITICAL(...) XBT_LOG(xbt_log_priority_critical, __VA_ARGS__)
503
504 /** @ingroup XBT_log
505  *  @hideinitializer
506  *  @brief Log at TRACE priority that we entered in current function.
507  */
508 #define XBT_IN       XBT_IN_F("")
509
510 /** @ingroup XBT_log
511  *  @hideinitializer
512  *  @brief Log at TRACE priority that we entered in current function, appending a user specified format.
513  */
514 #define XBT_IN_F(...) XBT_IN_F_(__VA_ARGS__, "")
515 #define XBT_IN_F_(fmt, ...) \
516   XBT_LOG(xbt_log_priority_trace, ">> begin of %s" fmt "%s", \
517           _XBT_FUNCTION, __VA_ARGS__)
518
519 /** @ingroup XBT_log
520  *  @hideinitializer
521  *  @brief Log at TRACE priority that we exited the current function.
522  */
523 #define XBT_OUT              XBT_LOG(xbt_log_priority_trace, "<< end of %s",       _XBT_FUNCTION)
524
525 /** @ingroup XBT_log
526  *  @hideinitializer
527  *  @brief Log at TRACE priority a message indicating that we reached that point.
528  */
529 #define XBT_HERE             XBT_LOG(xbt_log_priority_trace, "-- was here")
530
531 SG_END_DECL()
532 #endif                          /* ! _XBT_LOG_H_ */