lib: Add comments to event-related code

diff --git a/src/lib/event-log.c b/src/lib/event-log.c
index 02504674a24e6c7d9bcc4603072359230914d583..f8f2f79793e28d0934c8c05ff661054a3b7cd466 100644 (file)
--- a/src/lib/event-log.c
+++ b/src/lib/event-log.c
@@ -255,27 +255,37 @@ bool event_want_log_level(struct event *event, enum log_type level,
 {
        struct failure_context ctx = { .type = LOG_TYPE_DEBUG };
 
-       if (event->min_log_level <= level)
+       if (level >= event->min_log_level) {
+               /* Always log when level is at least this high */
                return TRUE;
+       }
 
-       if (event->debug_level_checked_filter_counter == event_filter_replace_counter)
+       if (event->debug_level_checked_filter_counter == event_filter_replace_counter) {
+               /* Log filters haven't changed since we last checked this, so
+                  we can rely on the last cached value. FIXME: this doesn't
+                  work correctly if event changes and the change affects
+                  whether the filters would match. */
                return event->sending_debug_log;
+       }
        event->debug_level_checked_filter_counter =
                event_filter_replace_counter;
 
-       if (event->forced_debug)
+       if (event->forced_debug) {
+               /* Debugging is forced for this event (and its children) */
                event->sending_debug_log = TRUE;
-
-       else if (global_debug_log_filter != NULL &&
-                event_filter_match_source(global_debug_log_filter, event,
-                                          source_filename, source_linenum, &ctx))
+       } else if (global_debug_log_filter != NULL &&
+                  event_filter_match_source(global_debug_log_filter, event,
+                                            source_filename, source_linenum, &ctx)) {
+               /* log_debug filter matched */
                event->sending_debug_log = TRUE;
-       else if (global_core_log_filter != NULL &&
-                event_filter_match_source(global_core_log_filter, event,
-                                          source_filename, source_linenum, &ctx))
+       } else if (global_core_log_filter != NULL &&
+                  event_filter_match_source(global_core_log_filter, event,
+                                            source_filename, source_linenum, &ctx)) {
+               /* log_core_filter matched */
                event->sending_debug_log = TRUE;
-       else
+       } else {
                event->sending_debug_log = FALSE;
+       }
        return event->sending_debug_log;
 }
 

diff --git a/src/lib/event-log.h b/src/lib/event-log.h
index 01600bc049fd7b4b48b834d53bbb3a554f1a2bfc..e5b7eb893ad20300e1125de35181c9569662d2eb 100644 (file)
--- a/src/lib/event-log.h
+++ b/src/lib/event-log.h
@@ -88,14 +88,21 @@ void e_log(struct event *event, enum log_type level,
                event_send_abort(_tmp_event); \
        } STMT_END
 
-/* Returns TRUE if debug event should be sent (either logged or sent to
-   stats). */
+/* Returns TRUE if event should be logged. Typically event_want_debug_log()
+   could be used in deciding whether to build an expensive debug log message
+   (e.g. requires extra disk IO). Note that if this is used, the actual
+   event being sent won't be matched against event filters because it's never
+   called. The result of the check is cached in the event, so repeated calls
+   are efficient. */
 bool event_want_log_level(struct event *event, enum log_type level,
                          const char *source_filename,
                          unsigned int source_linenum);
 #define event_want_log_level(_event, level) event_want_log_level((_event), (level), __FILE__, __LINE__)
 #define event_want_debug_log(_event) event_want_log_level((_event), LOG_TYPE_DEBUG)
 
+/* Returns TRUE if event should be processed (for logging or sending to stats).
+   The logging is checked with event_want_log_level() with the same caching
+   behavior.  */
 bool event_want_level(struct event *event, enum log_type level,
                      const char *source_filename,
                      unsigned int source_linenum);

diff --git a/src/lib/lib-event-private.h b/src/lib/lib-event-private.h
index d5cde14a87bc7b6c6788054a9215c1575fbc533b..a7f94448fecd3e60c4990372d6168e7a7a689552 100644 (file)
--- a/src/lib/lib-event-private.h
+++ b/src/lib/lib-event-private.h
@@ -37,7 +37,10 @@ struct event {
        event_log_message_callback_t *log_message_callback;
        void *log_message_callback_context;
        ARRAY(struct event_pointer) pointers;
+       /* If the event's log level is at least this high, log it. If it's
+          lower, check for debug log filters etc. */
        enum log_type min_log_level;
+
        bool log_prefix_from_system_pool:1;
        bool log_prefix_replace:1;
        bool passthrough:1;

diff --git a/src/lib/lib-event.h b/src/lib/lib-event.h
index d66c2dd91ffad88d7e815643bb38b6f563c94665..8609e74ef28e853d35eb60a20c79f707f672dc3f 100644 (file)
--- a/src/lib/lib-event.h
+++ b/src/lib/lib-event.h
@@ -239,7 +239,12 @@ event_set_source(struct event *event, const char *filename,
    it allow quickly finding which of the otherwise identical syscalls in the
    code generated the error. */
 struct event *event_set_always_log_source(struct event *event);
-/* Set minimum log level for the event */
+/* Set minimum normal log level for the event. By default events with INFO
+   level and higher are logged. This can be used to easily hide even the INFO
+   log lines unless some verbose-setting is enabled.
+
+   Note that this functionality is mostly independent of debug logging.
+   Don't use this to enable debug log - use event_set_forced_debug() instead. */
 struct event *event_set_min_log_level(struct event *event, enum log_type level);
 enum log_type event_get_min_log_level(const struct event *event);