diagnosticMgr.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_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