diagnosticMgr.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_DIAGNOSTIC_MGR_H
#define PXR_BASE_TF_DIAGNOSTIC_MGR_H
 
 
#include "pxr/pxr.h"
#include "pxr/base/tf/callContext.h"
#include "pxr/base/tf/debug.h"
#include "pxr/base/tf/diagnosticLite.h"
#include "pxr/base/tf/error.h"
#include "pxr/base/tf/singleton.h"
#include "pxr/base/tf/status.h"
#include "pxr/base/tf/stringUtils.h"
#include "pxr/base/tf/warning.h"
#include "pxr/base/tf/weakPtr.h"
#include "pxr/base/tf/enum.h"
#include "pxr/base/tf/api.h"
 
#include "pxr/base/arch/inttypes.h"
#include "pxr/base/arch/attributes.h"
#include "pxr/base/arch/functionLite.h"
 
#include <tbb/enumerable_thread_specific.h>
#include <tbb/spin_rw_mutex.h>
 
#include <atomic>
#include <cstdarg>
#include <list>
#include <string>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
TF_DEBUG_CODES(
    TF_LOG_STACK_TRACE_ON_ERROR,
    TF_LOG_STACK_TRACE_ON_WARNING,
    TF_ERROR_MARK_TRACKING,
    TF_PRINT_ALL_POSTED_ERRORS_TO_STDERR
    );
 
class TfError;
class TfErrorMark;
 
class TfDiagnosticMgr : public TfWeakBase {
public:
 
    typedef TfDiagnosticMgr This;
 
    typedef std::list<TfError> ErrorList;
 
    typedef ErrorList::iterator ErrorIterator;
 
    TF_API
    static std::string GetCodeName(const TfEnum &code);
 
    TF_API
    static std::string FormatDiagnostic(const TfEnum &code, 
            const TfCallContext &context, const std::string &msg, 
            const TfDiagnosticInfo &info);
 
    class Delegate {
      public:
        TF_API 
        virtual ~Delegate() = 0;
 
        virtual void IssueError(TfError const &err) = 0;
 
        virtual void IssueFatalError(TfCallContext const &context,
                                     std::string const &msg) = 0;
 
        virtual void IssueStatus(TfStatus const &status) = 0;
 
        virtual void IssueWarning(TfWarning const &warning) = 0;
 
    protected:
        TF_API
        void _UnhandledAbort() const;
    };
 
    TF_API static This &GetInstance() {
        return TfSingleton<This>::GetInstance();
    }
 
    TF_API
    void AddDelegate(Delegate* delegate);
 
    TF_API
    void RemoveDelegate(Delegate* delegate);
 
    TF_API
    void SetQuiet(bool quiet) { _quiet = quiet; }
    
    ErrorIterator GetErrorBegin() { return _errorList.local().begin(); }
 
    ErrorIterator GetErrorEnd() { return _errorList.local().end(); }
 
    TF_API
    ErrorIterator EraseError(ErrorIterator i);
 
    TF_API
    ErrorIterator EraseRange(ErrorIterator first, ErrorIterator last);
 
    TF_API
    void AppendError(TfError const &e);
    
    TF_API
    void PostError(TfEnum errorCode, const char* errorCodeString,
        TfCallContext const &context,  
        const std::string& commentary, TfDiagnosticInfo info,
        bool quiet);
    
    TF_API
    void PostError(const TfDiagnosticBase& diagnostic);
 
    TF_API
    void PostWarning(TfEnum warningCode, const char *warningCodeString,
        TfCallContext const &context, std::string const &commentary,
        TfDiagnosticInfo info, bool quiet) const;
 
    TF_API
    void PostWarning(const TfDiagnosticBase& diagnostic) const;
 
    TF_API
    void PostStatus(TfEnum statusCode, const char *statusCodeString,
        TfCallContext const &context, std::string const &commentary,
        TfDiagnosticInfo info, bool quiet) const;
 
    TF_API
    void PostStatus(const TfDiagnosticBase& diagnostic) const;
 
    [[noreturn]]
    TF_API
    void PostFatal(TfCallContext const &context, TfEnum statusCode,
                   std::string const &msg) const;
 
    bool HasActiveErrorMark() { return _errorMarkCounts.local() > 0; }
 
#if !defined(doxygen)
    //
    // Public, but *only* meant to be used by the TF_ERROR() macro.
    //
    class ErrorHelper {
      public:
        ErrorHelper(TfCallContext const &context, TfEnum errorCode,
                    const char* errorCodeString)
            : _context(context), _errorCode(errorCode),
              _errorCodeString(errorCodeString)
        {
        }
 
        TF_API
        void Post(const char* fmt, ...) const
            ARCH_PRINTF_FUNCTION(2,3);
 
        TF_API
        void PostQuietly(const char* fmt, ...) const
            ARCH_PRINTF_FUNCTION(2,3);
 
        TF_API
        void Post(const std::string& msg) const;
 
        TF_API
        void PostWithInfo(
                const std::string& msg,
                TfDiagnosticInfo info = TfDiagnosticInfo()) const;
 
        TF_API
        void PostQuietly(const std::string& msg,
                         TfDiagnosticInfo info = TfDiagnosticInfo()) const;
 
      private:
        TfCallContext _context;
        TfEnum _errorCode;
        const char *_errorCodeString;
    };
 
    struct WarningHelper {
        WarningHelper(TfCallContext const &context, TfEnum warningCode,
                      const char *warningCodeString)
            : _context(context), _warningCode(warningCode),
              _warningCodeString(warningCodeString)
        {
        }
 
        TF_API
        void Post(const char* fmt, ...) const
            ARCH_PRINTF_FUNCTION(2,3);
 
        TF_API
        void PostQuietly(const char* fmt, ...) const
            ARCH_PRINTF_FUNCTION(2,3);
 
        TF_API
        void Post(const std::string &str) const;
 
        TF_API
        void PostWithInfo(
                const std::string& msg,
                TfDiagnosticInfo info = TfDiagnosticInfo()) const;
 
        TF_API
        void PostQuietly(const std::string& msg) const;
 
      private:
        TfCallContext _context;
        TfEnum _warningCode;
        const char *_warningCodeString;
    };
 
    struct StatusHelper {
        StatusHelper(TfCallContext const &context, TfEnum statusCode,
                     const char *statusCodeString)
            : _context(context), _statusCode(statusCode),
              _statusCodeString(statusCodeString)
        {
        }
 
        TF_API
        void Post(const char* fmt, ...) const
            ARCH_PRINTF_FUNCTION(2,3);
 
        TF_API
        void PostQuietly(const char* fmt, ...) const
            ARCH_PRINTF_FUNCTION(2,3);
 
        TF_API
        void Post(const std::string &str) const;
 
        TF_API
        void PostWithInfo(
                const std::string& msg,
                TfDiagnosticInfo info = TfDiagnosticInfo()) const;
 
        TF_API
        void PostQuietly(const std::string& msg) const;
 
      private:
        TfCallContext _context;
        TfEnum _statusCode;
        const char *_statusCodeString;
    };
 
    struct FatalHelper {
        FatalHelper(TfCallContext const &context, TfEnum statusCode)
            : _context(context),
              _statusCode(statusCode)
        {
        }
        [[noreturn]]
        void Post(const std::string &str) const {
            This::GetInstance().PostFatal(_context, _statusCode, str);
        }
      private:
        TfCallContext _context;
        TfEnum _statusCode;
    };
        
#endif
    
private:
 
    TfDiagnosticMgr();
    virtual ~TfDiagnosticMgr();
    friend class TfSingleton<This>;
    
    // Return an iterator to the first error with serial number >= mark, or the
    // past-the-end iterator, if no such errors exist.
    TF_API
    ErrorIterator _GetErrorMarkBegin(size_t mark, size_t *nErrors);
 
    // Invoked by ErrorMark ctor.
    inline void _CreateErrorMark() { ++_errorMarkCounts.local(); }
 
    // Invoked by ErrorMark dtor.
    inline bool _DestroyErrorMark() { return --_errorMarkCounts.local() == 0; }
 
    // Report an error, either via delegate or print to stderr, and issue a
    // notice if this thread of execution is the main thread.
    void _ReportError(const TfError &err);
 
    // Splice the errors in src into this thread's local list.  Also reassign
    // serial numbers to all the spliced errors to ensure they work correctly
    // with local error marks.
    void _SpliceErrors(ErrorList &src);
 
    // Helper to append pending error messages to the crash log.
    void _AppendErrorsToLogText(ErrorIterator i);
 
    // Helper to fully rebuild the crash log error text when errors are erased
    // from the middle.
    void _RebuildErrorLogText();
 
    // Helper to actually publish log text into the Arch crash handler.
    void _SetLogInfoForErrors(std::vector<std::string> const &logText) const;
 
    // A guard used to protect reentrency when adding/removing
    // delegates as well as posting errors/warnings/statuses
    mutable tbb::enumerable_thread_specific<bool> _reentrantGuard;
 
    // The registered delegates.
    std::vector<Delegate*> _delegates;
 
    mutable tbb::spin_rw_mutex _delegatesMutex;
 
    // Global serial number for sorting.
    std::atomic<size_t> _nextSerial;
 
    // Thread-specific error list.
    tbb::enumerable_thread_specific<ErrorList> _errorList;
 
    // Thread-specific diagnostic log text for pending errors.
    struct _LogText {
        void AppendAndPublish(ErrorIterator i, ErrorIterator end);
        void RebuildAndPublish(ErrorIterator i, ErrorIterator end);
        
        std::pair<std::vector<std::string>,
                  std::vector<std::string>> texts;
        bool parity = false;
    private:
        void _AppendAndPublishImpl(bool clear,
                                   ErrorIterator i, ErrorIterator end);
    };
    tbb::enumerable_thread_specific<_LogText> _logText;
 
    // Thread-specific error mark counts.  Use a native key for best performance
    // here.
    tbb::enumerable_thread_specific<
        size_t, tbb::cache_aligned_allocator<size_t>,
        tbb::ets_key_per_instance> _errorMarkCounts;
 
    bool _quiet;
 
    friend class TfError;
    friend class TfErrorTransport;
    friend class TfErrorMark;
};
 
TF_API_TEMPLATE_CLASS(TfSingleton<TfDiagnosticMgr>);
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_BASE_TF_DIAGNOSTIC_MGR_H