debug.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_BASE_TF_DEBUG_H
#define PXR_BASE_TF_DEBUG_H
 
 
#include "pxr/pxr.h"
#include "pxr/base/tf/api.h"
#include "pxr/base/tf/tf.h"
#include "pxr/base/tf/enum.h"
#include "pxr/base/tf/preprocessorUtilsLite.h"
#include "pxr/base/tf/registryManager.h"
#include "pxr/base/tf/stopwatch.h"
#include "pxr/base/arch/attributes.h"
#include "pxr/base/arch/hints.h"
 
#include <atomic>
#include <cstdio>
#include <string>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class Tf_DebugSymbolRegistry;
 
 
class TfDebug {
    enum _NodeState { _NodeUninitialized, _NodeDisabled, _NodeEnabled };
 
public:
    template <class T>
    static void Enable(T val) {
        _SetNode(_GetNode(val), Tf_DebugGetEnumName(val), true);
    }
 
    template <class T>
    static void Disable(T val) {
        _SetNode(_GetNode(val), Tf_DebugGetEnumName(val), false);
    }
 
    template <class T>
    static void EnableAll() {
        const int n = _Traits<T>::NumCodes;
        for (int i = 0; i != n; ++i) {
            T code = static_cast<T>(i);
            _SetNode(_GetNode(code), Tf_DebugGetEnumName(code), true);
        }                              
    }
 
    template <class T>
    static void DisableAll() {
        const int n = _Traits<T>::NumCodes;
        for (int i = 0; i != n; ++i) {
            T code = static_cast<T>(i);
            _SetNode(_GetNode(code), Tf_DebugGetEnumName(code), false);
        }                              
    }
 
    template <class T>
    static bool IsEnabled(T val) {
        static_assert(_Traits<T>::IsDeclared,
                      "Must declare debug codes with TF_DEBUG_CODES()");
        if (_Traits<T>::CompileTimeEnabled) {
            _Node &node = _GetNode(val);
            _NodeState curState = node.state.load();
            if (ARCH_UNLIKELY(curState == _NodeUninitialized)) {
                _InitializeNode(_GetNode(val), Tf_DebugGetEnumName(val));
                curState = node.state.load();
            }
            return curState == _NodeEnabled;
        }
        return false;
    }
 
    template <class T>
    static bool IsCompileTimeEnabled() {
        static_assert(_Traits<T>::IsDeclared,
                      "Must declare debug codes with TF_DEBUG_CODES()");
        return _Traits<T>::CompileTimeEnabled;
    }
    
    template <class T>
    static size_t GetNumDebugCodes() {
        static_assert(_Traits<T>::IsDeclared,
                      "Must declare debug codes with TF_DEBUG_CODES()");
        return _Traits<T>::NumCodes;
    }
 
#if !defined(doxygen)
    struct _Helper {
        _Helper() = default;
        template <class Enum>
        explicit _Helper(Enum val) : _enumName(Tf_DebugGetEnumName(val)) {}
        TF_API void Msg(const std::string& msg) const;
        TF_API void Msg(const char* msg, ...) const ARCH_PRINTF_FUNCTION(2,3);
    private:
        char const * const _enumName = "<< no debug code >>";
    };
    
    struct Helper {
        template <class A1, class ...Args>
        static void Msg(char const *fmt, A1 &&a1, Args && ...args) {
            return _Helper().Msg(
                fmt, std::forward<A1>(a1), std::forward<Args>(args)...);
        }
        static void Msg(const std::string &msg) {
            return _Helper().Msg(msg);
        }
    };
#endif
 
    template <bool B>
    struct ScopeHelper {
        ScopeHelper(bool enabled, const char* name) {
            if ((active = enabled)) {
                str = name;
                TfDebug::_ScopedOutput(true, str);
            }
            else
                str = NULL;
        }
 
        ~ScopeHelper() {
            if (active)
                TfDebug::_ScopedOutput(false, str);
        }
 
        bool active;
        const char* str;
    };
 
    template <bool B>
    struct TimedScopeHelper {
        TimedScopeHelper(bool enabled, const char* fmt, ...) 
            ARCH_PRINTF_FUNCTION(3, 4);
        ~TimedScopeHelper();
 
        bool active;
        std::string str;
        TfStopwatch stopwatch;
    };
 
    TF_API
    static std::vector<std::string> SetDebugSymbolsByName(
        const std::string& pattern, bool value);
 
    TF_API
    static bool IsDebugSymbolNameEnabled(const std::string& name);
 
    TF_API
    static std::string GetDebugSymbolDescriptions();
 
    TF_API
    static std::vector<std::string> GetDebugSymbolNames();
 
    TF_API
    static std::string GetDebugSymbolDescription(const std::string& name);
 
    TF_API
    static void SetOutputFile(FILE *file);
    
    struct _Node;
 
    // Public, to be used in TF_DEBUG_ENVIRONMENT_SYMBOL() macro,
    // but not meant to be used otherwise.
    template <class T>
    static void _RegisterDebugSymbol(
        T enumVal, char const *name, char const *descrip) {
        static_assert(_Traits<T>::IsDeclared,
                      "Must declare debug codes with TF_DEBUG_CODES()");
        const int index = static_cast<int>(enumVal);
        const int numCodes = _Traits<T>::NumCodes;
        if (ARCH_UNLIKELY(index < 0 || index >= numCodes)) {
            _ComplainAboutInvalidSymbol(name);
            return;
        }
        _RegisterDebugSymbolImpl(&_GetNode(enumVal), name, descrip);
    }
 
    TF_API
    static void _RegisterDebugSymbolImpl(_Node *addr, char const *enumName,
                                         char const *descrip);
 
    // Unfortunately, we need to make both _Traits and _Node, below
    // public because of their use in macros.
    // Please treat both as a private data structures!
 
    template <class T>
    struct _Traits {
        static constexpr bool IsDeclared = false;
    };
 
    // Note: this structure gets initialized statically zero
    // (_NodeUninitialized) statically.
    struct _Node {
        mutable std::atomic<_NodeState> state;
    };
 
private:
    
    template <class T>
    struct _Data {
        static _Node nodes[_Traits<T>::NumCodes];
    };
 
    template <class T>
    static _Node &_GetNode(T val) {
        return _Data<T>::nodes[static_cast<int>(val)];
    }
 
    friend class Tf_DebugSymbolRegistry;
    
    TF_API
    static void _InitializeNode(_Node &node, char const *name);
 
    TF_API
    static void _ComplainAboutInvalidSymbol(char const *name);
 
    TF_API
    static void _SetNode(_Node &node, char const *name, bool state);
 
    TF_API
    static void _ScopedOutput(bool start, char const *str);
};
 
template <class T>
TfDebug::_Node TfDebug::_Data<T>::nodes[];
 
template <>
struct TfDebug::TimedScopeHelper<false> {
    TimedScopeHelper(bool, const char*, ...) 
        ARCH_PRINTF_FUNCTION(3, 4) { 
    }
};
 
#define TF_DEBUG_CODES(...)                                                  \
    TF_CONDITIONALLY_COMPILE_TIME_ENABLED_DEBUG_CODES(true, __VA_ARGS__)
 
#define TF_CONDITIONALLY_COMPILE_TIME_ENABLED_DEBUG_CODES(condition, ...)      \
    enum _TF_DEBUG_ENUM_NAME(__VA_ARGS__) {                                    \
        __VA_ARGS__ ,                                                          \
        TF_PP_CAT( _TF_DEBUG_ENUM_NAME(__VA_ARGS__), __PAST_END)               \
    };                                                                         \
    template <>                                                                \
    struct TfDebug::_Traits<_TF_DEBUG_ENUM_NAME(__VA_ARGS__)> {                \
        static constexpr bool IsDeclared = true;                               \
        static constexpr int NumCodes =                                        \
            TF_PP_CAT(_TF_DEBUG_ENUM_NAME(__VA_ARGS__), __PAST_END);           \
        static constexpr bool CompileTimeEnabled = (condition);                \
    };                                                                         \
    inline char const *                                                        \
    Tf_DebugGetEnumName(_TF_DEBUG_ENUM_NAME(__VA_ARGS__) val) {                \
        constexpr char const *CStrings[] = {                                   \
            TF_PP_FOR_EACH(_TF_DEBUG_MAKE_STRING, __VA_ARGS__)                 \
        };                                                                     \
        return CStrings[static_cast<int>(val)];                                \
    };
 
#define _TF_DEBUG_MAKE_STRING(x) #x,
 
// In the _TF_DEBUG_ENUM_NAME macro below we pass 'dummy' to
// _TF_DEBUG_FIRST_CODE as the second argument to ensure that we always
// have more than one argument as expected by _TF_DEBUG_FIRST_CODE.
#define _TF_DEBUG_ENUM_NAME(...)                                             \
    TF_PP_CAT(_TF_DEBUG_FIRST_CODE(__VA_ARGS__, dummy), __DebugCodes)
 
#define _TF_DEBUG_FIRST_CODE(first, ...) first
 
#define TF_DEBUG_MSG(enumVal, ...)                                             \
    if (!TfDebug::IsEnabled(enumVal)) /* empty */ ;                            \
    else TfDebug::_Helper(enumVal).Msg(__VA_ARGS__)
 
#define TF_DEBUG(enumVal)                                                      \
    if (!TfDebug::IsEnabled(enumVal)) /* empty */ ;                            \
    else TfDebug::_Helper(enumVal)
 
#define TF_INFO(x) TF_DEBUG(x)
 
#define TF_DEBUG_TIMED_SCOPE(enumVal, ...)                              \
    TfDebug::TimedScopeHelper<                                          \
        TfDebug::_Traits<                                               \
            std::decay<decltype(enumVal)>::type>::CompileTimeEnabled>   \
    TF_PP_CAT(local__TfScopeDebugSwObject, __LINE__)(                   \
        TfDebug::IsEnabled(enumVal), __VA_ARGS__)
 
#define TF_DEBUG_ENVIRONMENT_SYMBOL(VAL, descrip)                              \
    if (TfDebug::_Traits<                                                      \
        std::decay<decltype(VAL)>::type>::CompileTimeEnabled) {                \
        TF_ADD_ENUM_NAME(VAL);                                                 \
        TfDebug::_RegisterDebugSymbol(VAL, #VAL, descrip);                     \
    }
 
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif