ILogging.h#

// Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.
//
// NVIDIA CORPORATION and its licensors retain all intellectual property
// and proprietary rights in and to this software, related documentation
// and any modifications thereto. Any use, reproduction, disclosure or
// distribution of this software and related documentation without an express
// license agreement from NVIDIA CORPORATION is strictly prohibited.
//

#pragma once

#include "../Interface.h"
#include "../IObject.h"

#include <string>

#define carb_logging_ILogging_latest CARB_HEXVERSION(1, 4)
#ifndef carb_logging_ILogging
#    define carb_logging_ILogging CARB_HEXVERSION(1, 1)
#endif

#include "StandardLogger2.h"

namespace carb
{
namespace logging
{

struct StandardLogger;
class StandardLogger2;
struct Logger;
struct Logger2;

typedef void(CARB_ABI* SetLogLevelFn)(int32_t logLevel);

using ExtraFieldFlags = uint32_t;

constexpr ExtraFieldFlags fExtraFieldFlagNone = 0x00;

constexpr ExtraFieldFlags fExtraFieldFlagGlobal = 0x00;

constexpr ExtraFieldFlags fExtraFieldFlagThread = 0x01;

enum class LogSettingBehavior
{
    eInherit,
    eOverride
};

typedef void (*LogFn)(const char* source,
                      int32_t level,
                      const char* fileName,
                      const char* functionName,
                      int lineNumber,
                      const char* fmt,
                      ...);

namespace detail
{

enum class ExtraFieldOperation
{
    eCreateOrModify,
    eDelete,
    eExists,
};

} // namespace detail

// 'destroyStandardLoggerOld' is deprecated: Use StandardLogger2::release() instead
CARB_IGNOREWARNING_CLANG_WITH_PUSH("-Wdeprecated-declarations")

struct ILogging
{
    CARB_PLUGIN_INTERFACE_EX("carb::logging::ILogging", carb_logging_ILogging_latest, carb_logging_ILogging)

    void(CARB_ABI* log)(const char* source,
                        int32_t level,
                        const char* fileName,
                        const char* functionName,
                        int lineNumber,
                        const char* fmt,
                        ...) CARB_PRINTF_FUNCTION(6, 7);

    void(CARB_ABI* setLevelThreshold)(int32_t level);

    int32_t(CARB_ABI* getLevelThreshold)();

    void(CARB_ABI* setLogEnabled)(bool enabled);

    bool(CARB_ABI* isLogEnabled)();

    void(CARB_ABI* setLevelThresholdForSource)(const char* source, LogSettingBehavior behavior, int32_t level);

    void(CARB_ABI* setLogEnabledForSource)(const char* source, LogSettingBehavior behavior, bool enabled);

    void(CARB_ABI* reset)();

#if CARB_VERSION_ATLEAST(carb_logging_ILogging, 1, 3)
    static_assert(carb_logging_ILogging < CARB_HEXVERSION(2, 0), "Remove this function on major version change");
    CARB_DEPRECATED("Use addLogger() instead.") void(CARB_ABI* addLoggerOld)(Logger* logger);

    CARB_DEPRECATED("Use removeLogger() instead") void(CARB_ABI* removeLoggerOld)(Logger* logger);
#else
    void(CARB_ABI* addLogger)(Logger* logger);

    void(CARB_ABI* removeLogger)(Logger* logger);
#endif

#if CARB_VERSION_ATLEAST(carb_logging_ILogging, 1, 1)
    CARB_DEPRECATED("Use getDefaultLogger() instead") StandardLogger*(CARB_ABI* getDefaultLoggerOld)();

    CARB_DEPRECATED("Use createStandardLogger() instead") StandardLogger*(CARB_ABI* createStandardLoggerOld)();

    CARB_DEPRECATED("Use StandardLogger2::release() instead")
    void(CARB_ABI* destroyStandardLoggerOld)(StandardLogger* logger);
#else
    StandardLogger*(CARB_ABI* getDefaultLogger)();

    StandardLogger*(CARB_ABI* createStandardLogger)();

    void(CARB_ABI* destroyStandardLogger)(StandardLogger* logger);
#endif

    void(CARB_ABI* registerSource)(const char* source, SetLogLevelFn setLevelThreshold);

    void(CARB_ABI* unregisterSource)(const char* source);

    bool(CARB_ABI* setLogAsync)(bool logAsync);

    bool(CARB_ABI* getLogAsync)();

    void(CARB_ABI* flushLogs)();

#if CARB_VERSION_ATLEAST(carb_logging_ILogging, 1, 1)
    StandardLogger2*(CARB_ABI* getStandardLogger2)(StandardLogger* logger);

    StandardLogger2*(CARB_ABI* getDefaultLogger)();

    StandardLogger2*(CARB_ABI* createStandardLoggerInternal)();

    ObjectPtr<StandardLogger2> createStandardLogger()
    {
        using Ptr = ObjectPtr<StandardLogger2>;
        return Ptr(createStandardLoggerInternal(), Ptr::InitPolicy::eSteal);
    }
#endif

#if CARB_VERSION_ATLEAST(carb_logging_ILogging, 1, 3)
    void(CARB_ABI* addLogger)(Logger2* logger);

    bool(CARB_ABI* removeLogger)(Logger2* logger);
#endif

#if CARB_VERSION_ATLEAST(carb_logging_ILogging, 1, 4)
    bool(CARB_ABI* internalModifyExtraFieldValue)(const char* key,
                                                  const char* value,
                                                  detail::ExtraFieldOperation op,
                                                  ExtraFieldFlags flags);

    template <typename T>
    bool modifyExtraFieldValue(const char* key, T value, ExtraFieldFlags flags = fExtraFieldFlagNone)
    {
        return internalModifyExtraFieldValue(
            key, std::to_string(value).c_str(), detail::ExtraFieldOperation::eCreateOrModify, flags);
    }

    template <typename T>
    bool addExtraField(const char* key, T value, ExtraFieldFlags flags = fExtraFieldFlagNone)
    {
        return modifyExtraFieldValue(key, value, flags);
    }

    bool removeExtraField(const char* key, ExtraFieldFlags flags = fExtraFieldFlagNone)
    {
        return internalModifyExtraFieldValue(key, nullptr, detail::ExtraFieldOperation::eDelete, flags);
    }

    bool hasExtraField(const char* key, ExtraFieldFlags flags = fExtraFieldFlagNone)
    {
        return internalModifyExtraFieldValue(key, nullptr, detail::ExtraFieldOperation::eExists, flags);
    }
#endif
};

#if CARB_VERSION_ATLEAST(carb_logging_ILogging, 1, 4)
template <>
inline bool ILogging::modifyExtraFieldValue(const char* key, const char* value, ExtraFieldFlags flags)
{
    return internalModifyExtraFieldValue(key, value, detail::ExtraFieldOperation::eCreateOrModify, flags);
}

template <>
inline bool ILogging::modifyExtraFieldValue(const char* key, std::nullptr_t value, ExtraFieldFlags flags)
{
    return internalModifyExtraFieldValue(key, value, detail::ExtraFieldOperation::eCreateOrModify, flags);
}

template <>
inline bool ILogging::addExtraField(const char* key, const char* value, ExtraFieldFlags flags)
{
    CARB_ASSERT(value != nullptr);
    return internalModifyExtraFieldValue(key, value, detail::ExtraFieldOperation::eCreateOrModify, flags);
}
#endif

CARB_IGNOREWARNING_CLANG_POP
} // namespace logging
} // namespace carb