diagnostic.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_H
#define PXR_BASE_TF_DIAGNOSTIC_H


#include "pxr/pxr.h"
#include "pxr/base/arch/function.h"
#include "pxr/base/tf/diagnosticLite.h"
#include "pxr/base/tf/api.h"

#if defined(__cplusplus) || defined (doxygen)

#include "pxr/base/arch/hints.h"
#include "pxr/base/tf/diagnosticHelper.h"

#include <stddef.h>
#include <stdarg.h>
#include <string>

PXR_NAMESPACE_OPEN_SCOPE

// Note: diagnosticLite.h defines the various macros, but we'll document
// them here.  The following block is only for doxygen, not seen by a real
// compile.  To see the actual macro definition, look in diagnosticLite.h.

#if defined(doxygen)


#define TF_ERROR(...)

#define TF_CODING_ERROR(fmt, args)

#define TF_RUNTIME_ERROR(fmt, args)

#define TF_FATAL_ERROR(fmt, args)

#define TF_WARN(...)

#define TF_STATUS(...)

#define TF_AXIOM(cond)

#define TF_DEV_AXIOM(cond)

#define TF_VERIFY(cond [, format, ...])

#endif  /* defined(doxygen) */
           
//
// The rest of this is seen by a regular compile (or doxygen).
//

#if defined(__cplusplus) || defined(doxygen)

#define TF_FUNC_NAME()                                 \
    ArchGetPrettierFunctionName(__ARCH_FUNCTION__, __ARCH_PRETTY_FUNCTION__)

void Tf_TerminateHandler();

#if !defined(doxygen)

// Redefine these macros from DiagnosticLite to versions that will accept
// either string or printf-like args.

#ifdef TF_CODING_ERROR
#undef TF_CODING_ERROR
#endif
#define TF_CODING_ERROR(...)                            \
    Tf_PostErrorHelper(TF_CALL_CONTEXT,                 \
        TF_DIAGNOSTIC_CODING_ERROR_TYPE, __VA_ARGS__)

#ifdef TF_FATAL_CODING_ERROR
#undef TF_FATAL_CODING_ERROR
#endif
#define TF_FATAL_CODING_ERROR                                \
    Tf_DiagnosticHelper(TF_CALL_CONTEXT,                \
        TF_DIAGNOSTIC_CODING_ERROR_TYPE).IssueFatalError


#ifdef TF_CODING_WARNING
#undef TF_CODING_WARNING
#endif
#define TF_CODING_WARNING(...)                   \
    Tf_PostWarningHelper(TF_CALL_CONTEXT,               \
        TF_DIAGNOSTIC_CODING_ERROR_TYPE, __VA_ARGS__)

#ifdef TF_DIAGNOSTIC_WARNING
#undef TF_DIAGNOSTIC_WARNING
#endif
#define TF_DIAGNOSTIC_WARNING                                \
    Tf_DiagnosticHelper(TF_CALL_CONTEXT.Hide(),                \
        TF_DIAGNOSTIC_WARNING_TYPE).IssueWarning

#ifdef TF_RUNTIME_ERROR
#undef TF_RUNTIME_ERROR
#endif // TF_RUNTIME_ERROR
#define TF_RUNTIME_ERROR(...)                           \
    Tf_PostErrorHelper(TF_CALL_CONTEXT,                 \
        TF_DIAGNOSTIC_RUNTIME_ERROR_TYPE, __VA_ARGS__)

#ifdef TF_FATAL_ERROR
#undef TF_FATAL_ERROR
#endif // TF_FATAL_ERROR
#define TF_FATAL_ERROR                                  \
    Tf_DiagnosticHelper(TF_CALL_CONTEXT,                \
        TF_DIAGNOSTIC_FATAL_ERROR_TYPE).IssueFatalError

#ifdef TF_DIAGNOSTIC_FATAL_ERROR
#undef TF_DIAGNOSTIC_FATAL_ERROR
#endif // TF_DIAGNOSTIC_FATAL_ERROR
#define TF_DIAGNOSTIC_FATAL_ERROR                       \
    Tf_DiagnosticHelper(TF_CALL_CONTEXT,                \
        TF_DIAGNOSTIC_RUNTIME_ERROR_TYPE).IssueFatalError

#ifdef TF_DIAGNOSTIC_NONFATAL_ERROR
#undef TF_DIAGNOSTIC_NONFATAL_ERROR
#endif // TF_DIAGNOSTIC_NONFATAL_ERROR
#define TF_DIAGNOSTIC_NONFATAL_ERROR                        \
    Tf_DiagnosticHelper(TF_CALL_CONTEXT,                 \
        TF_DIAGNOSTIC_WARNING_TYPE).IssueWarning

// Redefine the following three macros from DiagnosticLite to versions that will
// accept the following sets of arguments:
// * MACRO(const char *, ...)
// * MACRO(const std::string &msg)
// * MACRO(ENUM, const char *, ...)
// * MACRO(ENUM, const std::string *msg)
// * MACRO(TfDiagnosticInfo, ENUM, const char *, ...)
// * MACRO(TfDiagnosticInfo, ENUM, const std::string *msg)

#ifdef TF_WARN
#undef TF_WARN
#endif // TF_WARN
#define TF_WARN(...)                                \
    Tf_PostWarningHelper(TF_CALL_CONTEXT, __VA_ARGS__)

#ifdef TF_STATUS
#undef TF_STATUS
#endif // TF_STATUS
#define TF_STATUS(...)                              \
    Tf_PostStatusHelper(TF_CALL_CONTEXT, __VA_ARGS__)

#ifdef TF_ERROR
#undef TF_ERROR
#endif // TF_ERROR
#define TF_ERROR(...)                              \
    Tf_PostErrorHelper(TF_CALL_CONTEXT, __VA_ARGS__)

#ifdef TF_QUIET_ERROR
#undef TF_QUIET_ERROR
#endif // TF_ERROR
#define TF_QUIET_ERROR(...)                              \
    Tf_PostQuietlyErrorHelper(TF_CALL_CONTEXT, __VA_ARGS__)

// See documentation above.
#define TF_VERIFY(cond, ...)                                                   \
    (ARCH_LIKELY(cond) ? true :                                                \
     Tf_FailedVerifyHelper(TF_CALL_CONTEXT, # cond,                            \
                           Tf_VerifyStringFormat(__VA_ARGS__)))

// Helpers for TF_VERIFY.
TF_API  bool
Tf_FailedVerifyHelper(TfCallContext const &context,
                      char const *condition, char const *msg);

// Helpers for TF_VERIFY.
inline char const *
Tf_VerifyStringFormat() { return nullptr; }
TF_API char const *
Tf_VerifyStringFormat(const char *format, ...) ARCH_PRINTF_FUNCTION(1, 2);

#endif // !doxygen

#endif // __cplusplus || doxygen

void TfSetProgramNameForErrors(std::string const& programName);

std::string TfGetProgramNameForErrors();

struct Tf_DiagnosticHelper {
    Tf_DiagnosticHelper(TfCallContext const &context,
                        TfDiagnosticType type) :
        _context(context),
        _type(type)
    {
    }
    
    TfCallContext const &GetContext() const { return _context; }
    TfDiagnosticType GetType() const { return _type; }

    TF_API void IssueError(std::string const &msg) const;
    TF_API void IssueError(char const *fmt, ...) const ARCH_PRINTF_FUNCTION(2,3);
    TF_API void IssueFatalError(std::string const &msg) const;
    TF_API void IssueFatalError(char const *fmt, ...) const ARCH_PRINTF_FUNCTION(2,3);
    TF_API void IssueWarning(std::string const &msg) const;
    TF_API void IssueWarning(char const *fmt, ...) const ARCH_PRINTF_FUNCTION(2,3);
    TF_API void IssueStatus(std::string const &msg) const;
    TF_API void IssueStatus(char const *fmt, ...) const ARCH_PRINTF_FUNCTION(2,3);

  private:
    TfCallContext _context;
    TfDiagnosticType _type;
};

#endif

TF_API
void TfInstallTerminateAndCrashHandlers();


PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_BASE_TF_DIAGNOSTIC_H