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, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 */

#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-internal.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;

    int fd;

    int indent_level;

    void initialise_categories_mask();

  public:
    DebugLogger()
        : categories_mask(1 << DEBUGLOG_CATEGORY_API), fd(-1), indent_level(0)
    { }

    ~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() {
#if __cplusplus >= 201703L
        return std::uncaught_exceptions();
#else
        return int(std::uncaught_exception());
#endif
    }

  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() {
#if __cplusplus >= 201703L
        return std::uncaught_exceptions();
#else
        return int(std::uncaught_exception());
#endif
    }

  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_)

#define RETURN(A) do { \
    xapian_logcall_return_type_ xapian_logcall_return_ = A; \
    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(A) return A
#define LOGLINE(a,b) (void)0
#define LOGVALUE(a,b) (void)0

#endif

#endif // XAPIAN_INCLUDED_DEBUGLOG_H