debuglog.h

Go to the documentation of this file.

 
/* Copyright (C) 2008,2009,2010,2011,2014,2015,2021,2023 Olly Betts
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, see
 * <https://www.gnu.org/licenses/>.
 */
 
#ifndef XAPIAN_INCLUDED_DEBUGLOG_H
#define XAPIAN_INCLUDED_DEBUGLOG_H
 
// In places where we include library code in non-library contexts, we can't
// have debug logging enabled, as the support functions aren't visible, so
// we define XAPIAN_REALLY_NO_DEBUG_LOG there.
#ifdef XAPIAN_REALLY_NO_DEBUG_LOG
# ifdef XAPIAN_DEBUG_LOG
#  undef XAPIAN_DEBUG_LOG
# endif
#endif
 
#ifdef XAPIAN_DEBUG_LOG
 
#include "output.h"
#include "pretty.h"
 
#include <cstring>
#include <ostream>
#include <sstream>
#include <string>
 
enum debuglog_categories {
    // Never wanted.
    DEBUGLOG_CATEGORY_NEVER = 0,
 
    DEBUGLOG_CATEGORY_API = ('A' - '@'),
 
    DEBUGLOG_CATEGORY_DB = ('D' - '@'),
 
    DEBUGLOG_CATEGORY_EXCEPTION = ('X' - '@'),
 
    DEBUGLOG_CATEGORY_EXPAND = ('E' - '@'),
 
    DEBUGLOG_CATEGORY_MATCH = ('M' - '@'),
 
    DEBUGLOG_CATEGORY_QUERYPARSER = ('Q' - '@'),
 
    DEBUGLOG_CATEGORY_REMOTE = ('R' - '@'),
 
    DEBUGLOG_CATEGORY_REPLICA = ('C' - '@'),
 
    DEBUGLOG_CATEGORY_SPELLING = ('S' - '@'),
 
    DEBUGLOG_CATEGORY_UNKNOWN = ('U' - '@'),
 
    DEBUGLOG_CATEGORY_WTCALC = ('W' - '@'),
 
    DEBUGLOG_CATEGORY_QUERY = ('Y' - '@'),
 
    DEBUGLOG_CATEGORY_ALWAYS = 31
};
 
class DebugLogger {
    void operator=(const DebugLogger&);
 
    DebugLogger(const DebugLogger&);
 
    unsigned int categories_mask = 1 << DEBUGLOG_CATEGORY_API;
 
    int fd = -1;
 
    int indent_level = 0;
 
    void initialise_categories_mask();
 
  public:
    DebugLogger() { }
 
    ~DebugLogger();
 
    bool is_category_wanted(debuglog_categories category) {
        // The argument will almost always be constant, so these inline checks
        // against DEBUGLOG_CATEGORY_ALWAYS and DEBUGLOG_CATEGORY_NEVER will
        // usually be optimised away, or become the only code path.
        if (category == DEBUGLOG_CATEGORY_ALWAYS) return true;
        if (category == DEBUGLOG_CATEGORY_NEVER) return false;
        if (fd == -1) initialise_categories_mask();
        return (categories_mask >> category) & 1;
    }
 
    void log_line(debuglog_categories category, const std::string& msg);
 
    void indent() { ++indent_level; }
 
    void outdent() {
        if (indent_level) --indent_level;
    }
};
 
namespace Xapian {
    typedef enum { NO_ARGS } NoArguments_;
}
 
inline std::ostream & operator<<(std::ostream &o, Xapian::NoArguments_) {
    return o;
}
 
using Xapian::NO_ARGS;
 
extern DebugLogger xapian_debuglogger_;
 
// Note that MSG can contain '<<' so we don't "protect" it with brackets.
#define LOGLINE_ALWAYS_(CATEGORY, MSG) do { \
    std::ostringstream xapian_debuglog_ostream_; \
    xapian_debuglog_ostream_ << MSG; \
    xapian_debuglogger_.log_line(CATEGORY, xapian_debuglog_ostream_.str()); \
} while (false)
 
// Note that MSG can contain '<<' so we don't "protect" it with brackets.
#define LOGLINE_(CATEGORY, MSG) do { \
    debuglog_categories xapian_debuglog_category_ = (CATEGORY); \
    if (xapian_debuglogger_.is_category_wanted(xapian_debuglog_category_)) { \
        LOGLINE_ALWAYS_(xapian_debuglog_category_, MSG); \
    } \
} while (false)
 
class DebugLogFunc {
    const void* this_ptr;
 
    debuglog_categories category;
 
    std::string func;
 
    int uncaught_exceptions;
 
    static int get_uncaught_exceptions() {
        return std::uncaught_exceptions();
    }
 
  public:
    DebugLogFunc(const void* this_ptr_, debuglog_categories category_,
                 const char* return_type, const char* func_name,
                 const std::string& params)
        : this_ptr(this_ptr_), category(category_),
          uncaught_exceptions(get_uncaught_exceptions())
    {
        if (is_category_wanted()) {
            func.assign(return_type);
            func += ' ';
            func += func_name;
            func += '(';
            func += params;
            func += ')';
            LOGLINE_ALWAYS_(category, '[' << this_ptr << "] " << func);
            xapian_debuglogger_.indent();
        }
    }
 
    void log_return_value(const std::string& return_value) {
        xapian_debuglogger_.outdent();
        LOGLINE_(category, '[' << this_ptr << "] " << func << " returned: " <<
                           return_value);
 
        // Flag that we've logged the return already.
        category = DEBUGLOG_CATEGORY_NEVER;
    }
 
    bool is_category_wanted() const {
        return xapian_debuglogger_.is_category_wanted(category);
    }
 
    ~DebugLogFunc() {
        if (!is_category_wanted()) return;
        xapian_debuglogger_.outdent();
        if (get_uncaught_exceptions() > uncaught_exceptions) {
            // An exception is causing the stack to be unwound.
            LOGLINE_(category, '[' << this_ptr << "] " << func <<
                               " exited due to exception");
        } else {
            LOGLINE_(category, '[' << this_ptr << "] " << func <<
                               " returned (not marked up for return logging)");
        }
    }
};
 
class DebugLogFuncVoid {
    const void* this_ptr;
 
    debuglog_categories category;
 
    std::string func;
 
    int uncaught_exceptions;
 
    static int get_uncaught_exceptions() {
        return std::uncaught_exceptions();
    }
 
  public:
    DebugLogFuncVoid(const void* this_ptr_, debuglog_categories category_,
                     const char* func_name,
                     const std::string& params)
        : this_ptr(this_ptr_), category(category_),
          uncaught_exceptions(get_uncaught_exceptions())
    {
        if (is_category_wanted()) {
            func.assign("void ");
            func += func_name;
            func += '(';
            func += params;
            func += ')';
            LOGLINE_ALWAYS_(category, '[' << this_ptr << "] " << func);
            xapian_debuglogger_.indent();
        }
    }
 
    DebugLogFuncVoid(const void* this_ptr_, debuglog_categories category_,
                     const std::string& params,
                     const char* class_name)
        : this_ptr(this_ptr_), category(category_),
          uncaught_exceptions(get_uncaught_exceptions())
    {
        if (is_category_wanted()) {
            func.assign(class_name);
            func += "::";
            // The ctor name is the last component if there are colons (e.g.
            // for Query::Internal, the ctor is Internal.
            const char* ctor_name = std::strrchr(class_name, ':');
            if (ctor_name)
                ++ctor_name;
            else
                ctor_name = class_name;
            func += ctor_name;
            func += '(';
            func += params;
            func += ')';
            LOGLINE_ALWAYS_(category, '[' << this_ptr << "] " << func);
            xapian_debuglogger_.indent();
        }
    }
 
    DebugLogFuncVoid(const void* this_ptr_, debuglog_categories category_,
                     const char* class_name)
        : this_ptr(this_ptr_), category(category_),
          uncaught_exceptions(get_uncaught_exceptions())
    {
        if (is_category_wanted()) {
            func.assign(class_name);
            func += "::~";
            // The dtor name is the last component if there are colons.
            const char* dtor_name = std::strrchr(class_name, ':');
            if (dtor_name)
                ++dtor_name;
            else
                dtor_name = class_name;
            func += dtor_name;
            func += "()";
            LOGLINE_(category, '[' << this_ptr << "] " << func);
            xapian_debuglogger_.indent();
        }
    }
 
    bool is_category_wanted() const {
        return xapian_debuglogger_.is_category_wanted(category);
    }
 
    ~DebugLogFuncVoid() {
        if (!is_category_wanted()) return;
        xapian_debuglogger_.outdent();
        const char* reason;
        if (get_uncaught_exceptions() > uncaught_exceptions) {
            // An exception is causing the stack to be unwound.
            reason = " exited due to exception";
        } else {
            reason = " returned";
        }
        LOGLINE_ALWAYS_(category, '[' << this_ptr << "] " << func << reason);
    }
};
 
#ifdef __GNUC__
// __attribute__((unused)) supported since at least GCC 2.95.3.
# define XAPIAN_UNUSED __attribute__((unused))
#else
# define XAPIAN_UNUSED
#endif
 
#define LOGCALL(CATEGORY, TYPE, FUNC, PARAMS) \
    typedef TYPE xapian_logcall_return_type_ XAPIAN_UNUSED; \
    std::string xapian_logcall_parameters_; \
    if (xapian_debuglogger_.is_category_wanted(DEBUGLOG_CATEGORY_##CATEGORY)) { \
        std::ostringstream xapian_logcall_ostream_; \
        PrettyOStream<std::ostringstream> xapian_logcall_stream_(xapian_logcall_ostream_); \
        xapian_logcall_stream_ << PARAMS; \
        xapian_logcall_parameters_ = xapian_logcall_ostream_.str(); \
    } \
    DebugLogFunc xapian_logcall_(static_cast<const void*>(this), \
                                 DEBUGLOG_CATEGORY_##CATEGORY, #TYPE, FUNC, \
                                 xapian_logcall_parameters_)
 
#define LOGCALL_VOID(CATEGORY, FUNC, PARAMS) \
    std::string xapian_logcall_parameters_; \
    if (xapian_debuglogger_.is_category_wanted(DEBUGLOG_CATEGORY_##CATEGORY)) { \
        std::ostringstream xapian_logcall_ostream_; \
        PrettyOStream<std::ostringstream> xapian_logcall_stream_(xapian_logcall_ostream_); \
        xapian_logcall_stream_ << PARAMS; \
        xapian_logcall_parameters_ = xapian_logcall_ostream_.str(); \
    } \
    DebugLogFuncVoid xapian_logcall_(static_cast<const void*>(this), \
                                     DEBUGLOG_CATEGORY_##CATEGORY, FUNC, \
                                     xapian_logcall_parameters_)
 
#define LOGCALL_CTOR(CATEGORY, CLASS, PARAMS) \
    std::string xapian_logcall_parameters_; \
    if (xapian_debuglogger_.is_category_wanted(DEBUGLOG_CATEGORY_##CATEGORY)) { \
        std::ostringstream xapian_logcall_ostream_; \
        PrettyOStream<std::ostringstream> xapian_logcall_stream_(xapian_logcall_ostream_); \
        xapian_logcall_stream_ << PARAMS; \
        xapian_logcall_parameters_ = xapian_logcall_ostream_.str(); \
    } \
    DebugLogFuncVoid xapian_logcall_(static_cast<const void*>(this), \
                                     DEBUGLOG_CATEGORY_##CATEGORY, \
                                     xapian_logcall_parameters_, CLASS)
 
#define LOGCALL_DTOR(CATEGORY, CLASS) \
    DebugLogFuncVoid xapian_logcall_(static_cast<const void*>(this), \
                                     DEBUGLOG_CATEGORY_##CATEGORY, CLASS)
 
#define LOGCALL_STATIC(CATEGORY, TYPE, FUNC, PARAMS) \
    typedef TYPE xapian_logcall_return_type_ XAPIAN_UNUSED; \
    std::string xapian_logcall_parameters_; \
    if (xapian_debuglogger_.is_category_wanted(DEBUGLOG_CATEGORY_##CATEGORY)) { \
        std::ostringstream xapian_logcall_ostream_; \
        PrettyOStream<std::ostringstream> xapian_logcall_stream_(xapian_logcall_ostream_); \
        xapian_logcall_stream_ << PARAMS; \
        xapian_logcall_parameters_ = xapian_logcall_ostream_.str(); \
    } \
    DebugLogFunc xapian_logcall_(0, DEBUGLOG_CATEGORY_##CATEGORY, #TYPE, FUNC, xapian_logcall_parameters_)
 
#define LOGCALL_STATIC_VOID(CATEGORY, FUNC, PARAMS) \
    std::string xapian_logcall_parameters_; \
    if (xapian_debuglogger_.is_category_wanted(DEBUGLOG_CATEGORY_##CATEGORY)) { \
        std::ostringstream xapian_logcall_ostream_; \
        PrettyOStream<std::ostringstream> xapian_logcall_stream_(xapian_logcall_ostream_); \
        xapian_logcall_stream_ << PARAMS; \
        xapian_logcall_parameters_ = xapian_logcall_ostream_.str(); \
    } \
    DebugLogFuncVoid xapian_logcall_(0, DEBUGLOG_CATEGORY_##CATEGORY, FUNC, xapian_logcall_parameters_)
 
/* Use __VA_ARGS__ so things like `RETURN({1, 2})` work. */
#define RETURN(...) do { \
    xapian_logcall_return_type_ xapian_logcall_return_ = __VA_ARGS__; \
    if (xapian_logcall_.is_category_wanted()) { \
        std::ostringstream xapian_logcall_ostream_; \
        PrettyOStream<std::ostringstream> xapian_logcall_stream_(xapian_logcall_ostream_); \
        xapian_logcall_stream_ << xapian_logcall_return_; \
        xapian_logcall_.log_return_value(xapian_logcall_ostream_.str()); \
    } \
    return xapian_logcall_return_; \
} while (false)
 
#define LOGLINE(a,b) LOGLINE_(DEBUGLOG_CATEGORY_##a, b)
 
#define LOGVALUE(a,b) LOGLINE_(DEBUGLOG_CATEGORY_##a, #b" = " << b)
 
#define RETURN_TYPE(...) __VA_ARGS__
 
#else
 
#define LOGCALL(CATEGORY, TYPE, FUNC, PARAMS) (void)0
#define LOGCALL_VOID(CATEGORY, FUNC, PARAMS) (void)0
#define LOGCALL_CTOR(CATEGORY, CLASS, PARAMS) (void)0
#define LOGCALL_DTOR(CATEGORY, CLASS) (void)0
#define LOGCALL_STATIC(CATEGORY, TYPE, FUNC, PARAMS) (void)0
#define LOGCALL_STATIC_VOID(CATEGORY, FUNC, PARAMS) (void)0
#define RETURN(...) return __VA_ARGS__
#define LOGLINE(a,b) (void)0
#define LOGVALUE(a,b) (void)0
 
#endif
 
#endif // XAPIAN_INCLUDED_DEBUGLOG_H