Add new output sink to the logger which is a user configurable callback function.

Author: martygrant

include/ur_api.h

@@ -226,6 +226,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_MEMORY_EXP = 226,         ///< Enumerator for ::urBindlessImagesImportExternalMemoryExp
     UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_SEMAPHORE_EXP = 227,      ///< Enumerator for ::urBindlessImagesImportExternalSemaphoreExp
     UR_FUNCTION_ENQUEUE_NATIVE_COMMAND_EXP = 228,                         ///< Enumerator for ::urEnqueueNativeCommandExp
+    UR_FUNCTION_LOADER_CONFIG_SET_LOGGER_CALLBACK = 229,                  ///< Enumerator for ::urLoaderConfigSetLoggerCallback
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -786,6 +787,30 @@ 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
+    void *pUserData         ///< [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.
+    void *pUserData                                ///< [in][out][optional] pointer to data to be passed to callback
+);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -9642,6 +9667,15 @@ 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;
+    void **ppUserData;
+} 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

@@ -1106,6 +1106,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

@@ -942,6 +942,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
     case UR_FUNCTION_ENQUEUE_NATIVE_COMMAND_EXP:
         os << "UR_FUNCTION_ENQUEUE_NATIVE_COMMAND_EXP";
         break;
+    case UR_FUNCTION_LOADER_CONFIG_SET_LOGGER_CALLBACK:
+        os << "UR_FUNCTION_LOADER_CONFIG_SET_LOGGER_CALLBACK";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -10266,6 +10269,26 @@ 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));
+
+    os << ", ";
+    os << ".pUserData = ";
+
+    ur::details::printPtr(os,
+                          *(params->ppUserData));
+
+    return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_platform_get_params_t type
 /// @returns
@@ -17315,6 +17338,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,29 @@ 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: void*
+      name: pUserData
+      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."
+    - type: void*
+      name: pUserData
+      desc: "[in][out][optional] pointer to data to be passed to callback"

scripts/core/registry.yml

@@ -592,6 +592,9 @@ etors:
 - name: ENQUEUE_NATIVE_COMMAND_EXP
   desc: Enumerator for $xEnqueueNativeCommandExp
   value: '228'
+- name: LOADER_CONFIG_SET_LOGGER_CALLBACK
+  desc: Enumerator for $xLoaderConfigSetLoggerCallback
+  value: '229'
 ---
 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,22 @@ class Logger {
         this->sink = std::move(legacySink);
     }
 
+    void setCallbackSinkFunction(ur_logger_output_callback_t cb,
+                                 void *pUserData) {
+        logger::Sink *rawBasePtr = this->sink.release();
+        logger::CallbackSink *derivedPtr =
+            dynamic_cast<logger::CallbackSink *>(rawBasePtr);
+
+        if (derivedPtr) {
+            derivedPtr->setCallback(cb, pUserData);
+
+            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,37 @@ 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, void *pUserData) {
+        callback = cb;
+        userData = pUserData;
+    }
+
+  private:
+    ur_logger_output_callback_t callback;
+    void *userData;
+
+    virtual void print([[maybe_unused]] logger::Level level,
+                       const std::string &msg) {
+        if (level >= flush_level) {
+            callback(msg.c_str(), userData);
+        }
+    }
+};
+
 inline std::unique_ptr<Sink> sink_from_str(std::string logger_name,
                                            std::string name,
                                            filesystem::path file_path = "",
@@ -209,6 +242,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

@@ -142,6 +142,7 @@ EXPORTS
 	urLoaderConfigRelease
 	urLoaderConfigRetain
 	urLoaderConfigSetCodeLocationCallback
+	urLoaderConfigSetLoggerCallback
 	urLoaderInit
 	urLoaderTearDown
 	urMemBufferCreate
@@ -361,6 +362,7 @@ EXPORTS
 	urPrintLoaderConfigReleaseParams
 	urPrintLoaderConfigRetainParams
 	urPrintLoaderConfigSetCodeLocationCallbackParams
+	urPrintLoaderConfigSetLoggerCallbackParams
 	urPrintLoaderInitParams
 	urPrintLoaderTearDownParams
 	urPrintMapFlags

source/loader/loader.map.in

@@ -142,6 +142,7 @@
 		urLoaderConfigRelease;
 		urLoaderConfigRetain;
 		urLoaderConfigSetCodeLocationCallback;
+		urLoaderConfigSetLoggerCallback;
 		urLoaderInit;
 		urLoaderTearDown;
 		urMemBufferCreate;
@@ -361,6 +362,7 @@
 		urPrintLoaderConfigReleaseParams;
 		urPrintLoaderConfigRetainParams;
 		urPrintLoaderConfigSetCodeLocationCallbackParams;
+		urPrintLoaderConfigSetLoggerCallbackParams;
 		urPrintLoaderInitParams;
 		urPrintLoaderTearDownParams;
 		urPrintMapFlags;