mallocTag.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_MALLOC_TAG_H
#define PXR_BASE_TF_MALLOC_TAG_H
 
#include "pxr/pxr.h"
#include "pxr/base/tf/api.h"
#include "pxr/base/tf/diagnosticLite.h"
#include "pxr/base/tf/eternalString.h"
#include "pxr/base/arch/hints.h"
 
#include <atomic>
#include <cstdlib>
#include <cstdint>
#include <iosfwd>
#include <new>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
 
// TfMallocTag collects by interposing the allocator via ArchMallocHook, which
// requires the old glibc-style hook variables.  When
// PXR_ARCH_SUPPORT_MALLOC_HOOKS is not defined (see pxr/pxr.h), no
// interposition is possible, so the entire collection implementation is omitted
// and this API compiles to minimal stubs.
//
// Callers need not care which build they are in.  The stub build behaves as a
// full build would where Initialize() fails.  Initialize() reports failure,
// IsInitialized() is always false, the queries report no memory, and tag
// push/pop compiles away.  Only report parsing and printing --
// CallTree::LoadReport(), Report(), and GetPrettyPrintString() -- remain fully
// functional, so a report captured elsewhere can still be read.
 
struct Tf_MallocPathNode;
 
class TfMallocTag {
 
    // Wrapper-type marking a tag name whose characters are immortal, so that
    // TfMallocTag may key on their address and adopt them without copying.
    struct _ImmortalName {
        char const *str;
    };
    
public:
    struct CallStackInfo;
 
    struct CallTree {
        struct PathNode {
            size_t nBytes,        
                   nBytesDirect;  
            size_t nAllocations;  
            std::string siteName; 
            std::vector<PathNode>
                        children; 
        };
 
        struct CallSite {
            std::string name;       
            size_t nBytes;          
        };
 
        enum PrintSetting {
            TREE = 0,                   
            CALLSITES,                  
            BOTH                        
        };
 
 
 
        TF_API
        std::string GetPrettyPrintString(PrintSetting setting = BOTH,
                                         size_t maxPrintedNodes = 100000) const;
 
        TF_API
        void Report(
            std::ostream &out,
            const std::string &rootName) const;
 
        TF_API
        void Report(
            std::ostream &out) const;
 
        TF_API
        bool LoadReport(
            std::istream &in);
 
 
 
        std::vector<CallSite> callSites;
 
        PathNode root;
 
        std::vector<CallStackInfo> capturedCallStacks;
    };
 
    struct CallStackInfo
    {
        std::vector<uintptr_t> stack;
 
        size_t size;
 
        size_t numAllocations;
    };
 
    TF_API static bool Initialize(std::string* errMsg = nullptr);
 
    TF_API static void Shutdown();
 
    static inline bool IsInitialized() {
#ifdef PXR_ARCH_SUPPORT_MALLOC_HOOKS
        return TfMallocTag::_initState
            .load(std::memory_order_acquire) == _Initialized;
#else
        // Constant false, so every caller below -- Auto, Pop,
        // GetCurrentStackState, StackOverride, PauseControl -- folds away
        // entirely rather than testing a variable at runtime.
        return false;
#endif
    }
 
    TF_API static void Clear();
 
    TF_API static size_t GetTotalBytes();
 
    TF_API static size_t GetMaxTotalBytes();
 
    TF_API static bool GetCallTree(CallTree* tree, bool skipRepeated = true);
 
    TF_API static std::string GetPerfStats(bool includePerThread=false);
 
private:
 
    struct _ThreadData;
 
public:
 
    class Auto {
    public:
        Auto(const Auto &) = delete;
        Auto& operator=(const Auto &) = delete;
 
        Auto(Auto &&) = delete;
        Auto& operator=(Auto &&) = delete;
 
        template <class Str, class... Strs>
        explicit Auto(Str &&name1, Strs &&... nameN)
            : _threadData(
                TfMallocTag::_Push(_TagName(std::forward<Str>(name1))))
            , _nTags(0) {
            if (_threadData) {
                // Accumulate _nTags; _Begin will not push null or empty tags.
                _nTags = 1;
                (..., (_nTags += (TfMallocTag::_Begin(
                                      _TagName(std::forward<Strs>(nameN)),
                                      _threadData) ? 1 : 0)));
            }
        }
 
        inline void Release() {
            if (_threadData) {
                TfMallocTag::_End(_nTags, _threadData);
                _threadData = nullptr;
            }
        }
 
        inline ~Auto() {
            Release();
        }
 
    private:
 
        // Is this tag argument a char array whose address we may treat as
        // immortal -- a string literal, or a static const char array?
        //
        // What we can actually test for is a const char array lvalue.  It is as
        // narrow as we can make it and deliberately not "any char array".
        // Unfortunately this can still accept objects that are not literals --
        // a `const char buf[N]` on the stack also passes, and no C++17
        // construct can tell that from a literal.  So this is the best we can
        // do, and remains a contract on callers rather than a check: a name
        // passed as a const char array must live as long as the program.
        template <class Str>
        static constexpr bool _IsImmortalCharArray =
            std::is_lvalue_reference_v<Str> &&
            std::is_array_v<std::remove_reference_t<Str>> &&
            std::is_const_v<
                std::remove_extent_t<std::remove_reference_t<Str>>>;
 
        template <class Str>
        static auto _TagName(Str &&name) {
            if constexpr (_IsImmortalCharArray<Str &&>) {
                return _ImmortalName { name };
            }
            else {
                return _TagNameNotArray(std::forward<Str>(name));
            }
        }
        // A TfEternalString's characters are immortal (and content-unique) so
        // route it exactly as a literal.  This exact match beats the
        // std::string const & overload below, which TfEternalString's implicit
        // conversion would otherwise reach.
        static _ImmortalName _TagNameNotArray(TfEternalString s) {
            return _ImmortalName { s.c_str() };
        }
        static char const *_TagNameNotArray(char const *cstr) { return cstr; }
        static char const *_TagNameNotArray(std::string const &str) {
            // Borrowed, not owned.  `str` may be a temporary in which case this
            // reference dangles and the c_str() pointer is invalidated at the
            // end of the full-expression that called us.  Both callers above
            // resolve the tag within that same full-expression, which makes
            // this safe.
            return str.c_str();
        }
 
        _ThreadData* _threadData;
        int _nTags;
 
        friend class TfMallocTag;
    };
 
    // An historical compatibility: in prior versions, Auto could accept only
    // one argument, so Auto2 existed to handle two arguments.  Now Auto can
    // accept any number of arguments, so Auto2 is just an alias for Auto.
    using Auto2 = Auto;
 
    // fwd for friendship.
    class StackOverride;
 
    class StackState {
    public:
        StackState() = default;
 
    private:
        explicit StackState(Tf_MallocPathNode *top) : _top(top) {}
 
        Tf_MallocPathNode *_top = nullptr;
 
        friend class TfMallocTag;
        friend class StackOverride;
    };
 
    class StackOverride {
    public:
        explicit StackOverride(StackState state)
            : _state(state)
            , _tls(state._top ? _Push() : nullptr) {}
 
        // Noncopyable, nonmovable.
        StackOverride(const StackOverride &) = delete;
        StackOverride &operator=(const StackOverride &) = delete;
 
        ~StackOverride() {
            if (ARCH_UNLIKELY(_tls)) {
                _Pop();
            }
        }
        
    private:
        TF_API _ThreadData *_Push() const;
        TF_API void _Pop() const;
    
        const StackState _state;
        _ThreadData *_tls;
    
        friend class TfMallocTag;
    };
 
    class PauseControl {
    public:
        PauseControl(PauseControl const &) = delete;
        PauseControl &operator=(PauseControl const &) = delete;
 
        PauseControl(PauseControl &&other) noexcept
            : _td(std::exchange(other._td, nullptr))
            , _scope(std::exchange(other._scope, _NotPaused)) {}
 
        PauseControl &operator=(PauseControl &&other) noexcept {
            if (this != &other) {
                if (IsPaused()) {
                    Unpause();
                }
                _td = std::exchange(other._td, nullptr);
                _scope = std::exchange(other._scope, _NotPaused);
            }
            return *this;
        }
 
        ~PauseControl() {
            Unpause();
        }
 
        void PauseThisThread() {
            if (IsPaused()) {
                return;
            }
            _Pause(_ThisThread);
        }
 
        void PauseAllThreads() {
            if (IsPaused()) {
                return;
            }
            _Pause(_AllThreads);
        }
 
        void Unpause() {
            if (IsPaused()) {
                _Unpause();
            }
        }
 
        bool IsPaused() const {
            return _scope != _NotPaused;
        }
 
    private:
        enum _Scope {
            _NotPaused, _ThisThread, _AllThreads
        };
 
        // Only constructible via TfMallocTag factory functions.
        explicit PauseControl(_Scope desired) {
            if (desired != _NotPaused) {
                _Pause(desired);
            }
        }
 
        TF_API
        void _Pause(_Scope desired);
 
        TF_API
        void _Unpause();
 
        _ThreadData *_td    = nullptr;
        _Scope       _scope = _NotPaused;
 
        friend class TfMallocTag;
    };
        
    [[nodiscard]] static PauseControl PauseThisThread() {
        return PauseControl(PauseControl::_ThisThread);
    }
 
    [[nodiscard]] static PauseControl PauseAllThreads() {
        return PauseControl(PauseControl::_AllThreads);
    }
 
    [[nodiscard]] static PauseControl DeferredPause() {
        return PauseControl(PauseControl::_NotPaused);
    }    
    
 
    static StackState GetCurrentStackState() {
        return ARCH_UNLIKELY(TfMallocTag::IsInitialized())
            ? _GetCurrentStackState() : StackState {};
    }
 
    static void Push(const std::string& name) {
        _Push(name.c_str());
    }
 
    static void Push(const char* name) {
        _Push(name);
    }
 
    static void Push(TfEternalString name) {
        _Push(_ImmortalName { name.c_str() });
    }
 
    static void Pop() {
        if (TfMallocTag::IsInitialized()) {
            _PopChecked();
        }
    }
 
    TF_API static void SetDebugMatchList(const std::string& matchList);
 
    TF_API static void
    SetCapturedMallocStacksMatchList(const std::string& matchList);
 
    TF_API static std::vector<std::vector<uintptr_t> > GetCapturedMallocStacks();
 
private:
#ifdef PXR_ARCH_SUPPORT_MALLOC_HOOKS
    // Atomic initialization state -- valid transitions are from N -> N+1
    // cyclically, and from _Initializing -> _NotInitialized if initialization
    // fails.
    enum _InitState {
        _NotInitialized,
        _Initializing,
        _Initialized,
        _ShuttingDown
    };
#endif
 
    friend struct _TemporaryDisabler;
 
    friend struct Tf_MallocGlobalData;
 
    static inline _ThreadData *_Push(char const *name) {
        if (TfMallocTag::IsInitialized()) {
            return _Begin(name);
        }
        return nullptr;
    }
    static inline _ThreadData *_Push(_ImmortalName name) {
        if (TfMallocTag::IsInitialized()) {
            return _Begin(name);
        }
        return nullptr;
    }
 
    TF_API static _ThreadData *
    _Begin(char const *name, _ThreadData *threadData = nullptr);
 
    TF_API static _ThreadData *
    _Begin(_ImmortalName name, _ThreadData *threadData = nullptr);
    
    // The Auto/StackOverride exit path.  `threadData` must be non-null and
    // `nTags` must match the number of pushes that were actually performed;
    // both hold by construction at the only call site (Auto::Release()).
    TF_API static void _End(int nTags, _ThreadData *threadData);
 
    // The manual Pop() path, which tolerates an unbalanced pop.  Kept separate
    // from _End() so that the Auto path pays nothing for the check.
    TF_API static void _PopChecked();
 
    TF_API static StackState _GetCurrentStackState();
    
    static void* _MallocWrapper(size_t, const void*);
    static void* _ReallocWrapper(void*, size_t, const void*);
    static void* _MemalignWrapper(size_t, size_t, const void*);
    static void  _FreeWrapper(void*, const void*);
 
    friend class TfMallocTag::Auto;
    class Tls;
    friend class TfMallocTag::Tls;
#ifdef PXR_ARCH_SUPPORT_MALLOC_HOOKS
    TF_API static std::atomic<_InitState> _initState;
#endif
};
 
using TfAutoMallocTag = TfMallocTag::Auto;
 
using TfAutoMallocTag2 = TfMallocTag::Auto;
 
//
PXR_NAMESPACE_CLOSE_SCOPE                                                 
 
#define TF_MALLOC_TAG_NEW(...)                                                \
    /* this is for STL purposes */                                            \
    ARCH_ALWAYS_INLINE inline void* operator new(::std::size_t, void* ptr) {  \
        return ptr;                                                           \
    }                                                                         \
                                                                              \
    ARCH_ALWAYS_INLINE inline void* operator new(::std::size_t s) {           \
        PXR_NS::TfAutoMallocTag tag(__VA_ARGS__);                             \
        return ::operator new(s, std::nothrow);                               \
    }                                                                         \
                                                                              \
    ARCH_ALWAYS_INLINE inline void* operator new[](::std::size_t s) {         \
        PXR_NS::TfAutoMallocTag tag(__VA_ARGS__);                             \
        return ::operator new[](s, std::nothrow);                             \
    }                                                                         \
                                                                              \
    /* Required due to the placement-new override above. */                   \
    ARCH_ALWAYS_INLINE inline void operator delete(void* ptr, void* place) {} \
                                                                              \
    ARCH_ALWAYS_INLINE inline void operator delete(void* ptr, size_t) {       \
        ::operator delete(ptr, std::nothrow);                                 \
    }                                                                         \
                                                                              \
    ARCH_ALWAYS_INLINE inline void operator delete[] (void* ptr, size_t) {    \
        ::operator delete[](ptr, std::nothrow);                               \
    }                                                                         \
 
#endif