Add new output sink to the logger which is a user configurable callba…

…ck function.

include/ur_api.h

@@ -225,6 +225,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_ENQUEUE_TIMESTAMP_RECORDING_EXP = 223,                         ///< Enumerator for ::urEnqueueTimestampRecordingExp
     UR_FUNCTION_ENQUEUE_KERNEL_LAUNCH_CUSTOM_EXP = 224,                        ///< Enumerator for ::urEnqueueKernelLaunchCustomExp
     UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE = 225,                    ///< Enumerator for ::urKernelGetSuggestedLocalWorkSize
+    UR_FUNCTION_LOADER_CONFIG_SET_LOGGER_CALLBACK = 226,                       ///< Enumerator for ::urLoaderConfigSetLoggerCallback
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -784,6 +785,28 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urLoaderTearDown(
     void);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Callback function to retrieve output from the logger.
+typedef void (*ur_logger_output_callback_t)(
+    const char *pLoggerMsg ///< [in][out] pointer to data to be passed to callback
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Set a callback function for use by the logger to retrieve logging
+///        output.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pfnLoggerCallback`
+UR_APIEXPORT ur_result_t UR_APICALL
+urLoaderConfigSetLoggerCallback(
+    ur_logger_output_callback_t pfnLoggerCallback ///< [in] Function pointer to callback from the logger.
+);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -9516,6 +9539,14 @@ typedef struct ur_loader_config_set_code_location_callback_params_t {
     void **ppUserData;
 } ur_loader_config_set_code_location_callback_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urLoaderConfigSetLoggerCallback
+/// @details Each entry is a pointer to the parameter passed to the function;
+///     allowing the callback the ability to modify the parameter's value
+typedef struct ur_loader_config_set_logger_callback_params_t {
+    ur_logger_output_callback_t *ppfnLoggerCallback;
+} ur_loader_config_set_logger_callback_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urPlatformGet
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_print.h

@@ -1074,6 +1074,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigEnableLayerParams(const s
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigSetCodeLocationCallbackParams(const struct ur_loader_config_set_code_location_callback_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_loader_config_set_logger_callback_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigSetLoggerCallbackParams(const struct ur_loader_config_set_logger_callback_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_platform_get_params_t struct
 /// @returns

include/ur_print.hpp

@@ -932,6 +932,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
     case UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE:
         os << "UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE";
         break;
+    case UR_FUNCTION_LOADER_CONFIG_SET_LOGGER_CALLBACK:
+        os << "UR_FUNCTION_LOADER_CONFIG_SET_LOGGER_CALLBACK";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -10101,6 +10104,20 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
     return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_loader_config_set_logger_callback_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_loader_config_set_logger_callback_params_t *params) {
+
+    os << ".pfnLoggerCallback = ";
+
+    os << reinterpret_cast<void *>(
+        *(params->ppfnLoggerCallback));
+
+    return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_platform_get_params_t type
 /// @returns
@@ -17042,6 +17059,9 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os, ur_function_
     case UR_FUNCTION_LOADER_CONFIG_SET_CODE_LOCATION_CALLBACK: {
         os << (const struct ur_loader_config_set_code_location_callback_params_t *)params;
     } break;
+    case UR_FUNCTION_LOADER_CONFIG_SET_LOGGER_CALLBACK: {
+        os << (const struct ur_loader_config_set_logger_callback_params_t *)params;
+    } break;
     case UR_FUNCTION_PLATFORM_GET: {
         os << (const struct ur_platform_get_params_t *)params;
     } break;

scripts/core/INTRO.rst

@@ -202,12 +202,12 @@ By default, no messages are printed.
 
 By default, there is a guarantee that *error* messages are flushed immediately. One can change this behavior to flush on lower-level messages.
 
-Loggers redirect messages to *stdout*, *stderr*, or a file (default: *stderr*).
+Loggers redirect messages to *stdout*, *stderr*, a file or a user configurable callback function (default: *stderr*).
 
 All of these logging options can be set with **UR_LOG_LOADER** and **UR_LOG_NULL** environment variables described in the **Environment Variables** section below.
 Both of these environment variables have the same syntax for setting logger options:
 
-  "[level:debug|info|warning|error];[flush:<debug|info|warning|error>];[output:stdout|stderr|file,<path>]"
+  "[level:debug|info|warning|error];[flush:<debug|info|warning|error>];[output:stdout|stderr|file,<path>|callback]"
 
   * level - a log level, meaning that only messages from this level and above are printed,
             possible values, from the lowest level to the highest one: *debug*, *info*, *warning*, *error*,

scripts/core/loader.yml

@@ -225,3 +225,23 @@ ordinal: "1"
 params: []
 returns:
     - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
+--- #--------------------------------------------------------------------------
+type: fptr_typedef
+desc: "Callback function to retrieve output from the logger."
+name: $x_logger_output_callback_t
+return: "void"
+params:
+    - type: const char*
+      name: pLoggerMsg
+      desc: "[in][out] pointer to data to be passed to callback"
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Set a callback function for use by the logger to retrieve logging output."
+class: $xLoaderConfig
+loader_only: True
+name: SetLoggerCallback
+decl: static
+params:
+    - type: $x_logger_output_callback_t
+      name: pfnLoggerCallback
+      desc: "[in] Function pointer to callback from the logger."

scripts/core/registry.yml

@@ -589,6 +589,9 @@ etors:
 - name: KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE
   desc: Enumerator for $xKernelGetSuggestedLocalWorkSize
   value: '225'
+- name: LOADER_CONFIG_SET_LOGGER_CALLBACK
+  desc: Enumerator for $xLoaderConfigSetLoggerCallback
+  value: '226'
 ---
 type: enum
 desc: Defines structure types

source/common/logger/ur_logger_details.hpp

@@ -101,15 +101,13 @@ class Logger {
         if (!sink) {
             return;
         }
-
         if (isLegacySink) {
             sink->log(level, p.message, std::forward<Args>(args)...);
             return;
         }
         if (level < this->level) {
             return;
         }
-
         sink->log(level, format, std::forward<Args>(args)...);
     }
 
@@ -118,6 +116,21 @@ class Logger {
         this->sink = std::move(legacySink);
     }
 
+    void setCallbackSinkFunction(ur_logger_output_callback_t cb) {
+        logger::Sink *rawBasePtr = this->sink.release();
+        logger::CallbackSink *derivedPtr =
+            dynamic_cast<logger::CallbackSink *>(rawBasePtr);
+
+        if (derivedPtr) {
+            derivedPtr->setCallback(cb);
+
+            this->sink.reset(derivedPtr);
+        } else {
+            // output a failure here??
+            this->sink.reset(rawBasePtr);
+        }
+    }
+
   private:
     logger::Level level;
     std::unique_ptr<logger::Sink> sink;

source/common/logger/ur_sinks.hpp

@@ -7,10 +7,12 @@
 #define UR_SINKS_HPP 1
 
 #include <fstream>
+#include <functional>
 #include <iostream>
 #include <mutex>
 #include <sstream>
 
+#include "ur_api.h"
 #include "ur_filesystem_resolved.hpp"
 #include "ur_level.hpp"
 #include "ur_print.hpp"
@@ -195,6 +197,33 @@ class FileSink : public Sink {
     std::ofstream ofstream;
 };
 
+class CallbackSink : public Sink {
+  public:
+    CallbackSink(std::string logger_name, bool skip_prefix = false,
+                 bool skip_linebreak = false)
+        : Sink(std::move(logger_name), skip_prefix, skip_linebreak) {}
+
+    CallbackSink(std::string logger_name, Level flush_lvl, bool skip_prefix,
+                 bool skip_linebreak)
+        : CallbackSink(std::move(logger_name), skip_prefix, skip_linebreak) {
+        this->flush_level = flush_lvl;
+    }
+
+    ~CallbackSink() = default;
+
+    void setCallback(ur_logger_output_callback_t cb) { callback = cb; }
+
+  private:
+    ur_logger_output_callback_t callback;
+
+    virtual void print([[maybe_unused]] logger::Level level,
+                       const std::string &msg) {
+        if (level >= flush_level) {
+            callback(msg.c_str());
+        }
+    }
+};
+
 inline std::unique_ptr<Sink> sink_from_str(std::string logger_name,
                                            std::string name,
                                            filesystem::path file_path = "",
@@ -209,6 +238,9 @@ inline std::unique_ptr<Sink> sink_from_str(std::string logger_name,
     } else if (name == "file" && !file_path.empty()) {
         return std::make_unique<logger::FileSink>(logger_name, file_path,
                                                   skip_prefix, skip_linebreak);
+    } else if (name == "callback" && !file_path.empty()) {
+        return std::make_unique<logger::CallbackSink>(logger_name, skip_prefix,
+                                                      skip_linebreak);
     }
 
     throw std::invalid_argument(

source/loader/loader.def.in

@@ -141,6 +141,7 @@ EXPORTS
 	urLoaderConfigRelease
 	urLoaderConfigRetain
 	urLoaderConfigSetCodeLocationCallback
+	urLoaderConfigSetLoggerCallback
 	urLoaderInit
 	urLoaderTearDown
 	urMemBufferCreate
@@ -355,6 +356,7 @@ EXPORTS
 	urPrintLoaderConfigReleaseParams
 	urPrintLoaderConfigRetainParams
 	urPrintLoaderConfigSetCodeLocationCallbackParams
+	urPrintLoaderConfigSetLoggerCallbackParams
 	urPrintLoaderInitParams
 	urPrintLoaderTearDownParams
 	urPrintMapFlags

source/loader/loader.map.in

@@ -141,6 +141,7 @@
 		urLoaderConfigRelease;
 		urLoaderConfigRetain;
 		urLoaderConfigSetCodeLocationCallback;
+		urLoaderConfigSetLoggerCallback;
 		urLoaderInit;
 		urLoaderTearDown;
 		urMemBufferCreate;
@@ -355,6 +356,7 @@
 		urPrintLoaderConfigReleaseParams;
 		urPrintLoaderConfigRetainParams;
 		urPrintLoaderConfigSetCodeLocationCallbackParams;
+		urPrintLoaderConfigSetLoggerCallbackParams;
 		urPrintLoaderInitParams;
 		urPrintLoaderTearDownParams;
 		urPrintMapFlags;

source/loader/ur_lib.cpp

@@ -215,6 +215,17 @@ urLoaderConfigSetCodeLocationCallback(ur_loader_config_handle_t hLoaderConfig,
     return UR_RESULT_SUCCESS;
 }
 
+ur_result_t
+urLoaderConfigSetLoggerCallback(ur_logger_output_callback_t pfnLoggerCallback) {
+    if (!pfnLoggerCallback) {
+        return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+    }
+
+    logger::get_logger().setCallbackSinkFunction(pfnLoggerCallback);
+
+    return UR_RESULT_SUCCESS;
+}
+
 ur_result_t urDeviceGetSelected(ur_platform_handle_t hPlatform,
                                 ur_device_type_t DeviceType,
                                 uint32_t NumEntries,

source/loader/ur_lib.hpp

@@ -104,6 +104,8 @@ ur_result_t
 urLoaderConfigSetCodeLocationCallback(ur_loader_config_handle_t hLoaderConfig,
                                       ur_code_location_callback_t pfnCodeloc,
                                       void *pUserData);
+ur_result_t
+urLoaderConfigSetLoggerCallback(ur_logger_output_callback_t pfnLoggerCallback);
 
 ur_result_t urDeviceGetSelected(ur_platform_handle_t hPlatform,
                                 ur_device_type_t DeviceType,

source/loader/ur_libapi.cpp

@@ -252,6 +252,26 @@ ur_result_t UR_APICALL urLoaderTearDown(void) try {
     return exceptionToResult(std::current_exception());
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Set a callback function for use by the logger to retrieve logging
+///        output.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pfnLoggerCallback`
+ur_result_t UR_APICALL urLoaderConfigSetLoggerCallback(
+    ur_logger_output_callback_t
+        pfnLoggerCallback ///< [in] Function pointer to callback from the logger.
+    ) try {
+    return ur_lib::urLoaderConfigSetLoggerCallback(pfnLoggerCallback);
+} catch (...) {
+    return exceptionToResult(std::current_exception());
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Retrieves all available adapters
 ///

source/loader/ur_print.cpp

@@ -1960,6 +1960,14 @@ ur_result_t urPrintLoaderConfigSetCodeLocationCallbackParams(
     return str_copy(&ss, buffer, buff_size, out_size);
 }
 
+ur_result_t urPrintLoaderConfigSetLoggerCallbackParams(
+    const struct ur_loader_config_set_logger_callback_params_t *params,
+    char *buffer, const size_t buff_size, size_t *out_size) {
+    std::stringstream ss;
+    ss << params;
+    return str_copy(&ss, buffer, buff_size, out_size);
+}
+
 ur_result_t
 urPrintMemImageCreateParams(const struct ur_mem_image_create_params_t *params,
                             char *buffer, const size_t buff_size,

source/ur_api.cpp

@@ -229,6 +229,25 @@ ur_result_t UR_APICALL urLoaderTearDown(void) {
     return result;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Set a callback function for use by the logger to retrieve logging
+///        output.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pfnLoggerCallback`
+ur_result_t UR_APICALL urLoaderConfigSetLoggerCallback(
+    ur_logger_output_callback_t
+        pfnLoggerCallback ///< [in] Function pointer to callback from the logger.
+) {
+    ur_result_t result = UR_RESULT_SUCCESS;
+    return result;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Retrieves all available adapters
 ///

test/unit/logger/fixtures.hpp

@@ -96,4 +96,15 @@ class DefaultLoggerWithFileSink : public UniquePtrLoggerWithFilesink {
     }
 };
 
+class LoggerWithCallbackSink : public LoggerCommonSetup {
+  protected:
+    std::unique_ptr<logger::Logger> logger;
+
+    void SetUp() override {
+        logger = std::make_unique<logger::Logger>(
+            logger::Level::WARN,
+            std::make_unique<logger::CallbackSink>(logger_name));
+    }
+};
+
 #endif // UR_UNIT_LOGGER_TEST_FIXTURES_HPP