debug.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache 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 {
        static TF_API void Msg(const std::string& msg);
        static TF_API void Msg(const char* msg, ...) ARCH_PRINTF_FUNCTION(1,2);
    };
#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().Msg(__VA_ARGS__)

#define TF_DEBUG(enumVal)                                               \
    if (!TfDebug::IsEnabled(enumVal)) /* empty */ ; else TfDebug::Helper()

#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