2020import ctypes
2121import logging
2222import threading
23+ from typing import Callable , Optional
2324
2425from cuda .bindings import driver as _driver
2526from cuda .core ._utils .cuda_utils import handle_return
4243 int (_driver .CUlogLevel .CU_LOG_LEVEL_WARNING ): logging .WARNING ,
4344}
4445
46+ # User-supplied hook that customizes how each driver log message is
47+ # displayed/handled; see the ``callback`` parameter of
48+ # :func:`register_cuda_log_bridge`.
49+ #
50+ # callback(logger, level, message) -> None
51+ #
52+ # ``logger`` is the same :class:`logging.Logger` passed to (or defaulted by)
53+ # :func:`register_cuda_log_bridge`, ``level`` is the already-mapped
54+ # ``logging.ERROR`` / ``logging.WARNING`` level, and ``message`` is the
55+ # decoded driver log text (without the ``[CUDA Driver]`` prefix added by the
56+ # default formatter).
57+ LogCallback = Callable [[logging .Logger , int , str ], None ]
58+
4559_lock = threading .Lock ()
4660# Must hold a reference to the ctypes callback for as long as it is
4761# registered: once it is garbage collected, the driver would be left
5165_callback_handle = None # CUlogsCallbackHandle, needed to unregister
5266
5367
54- def _make_c_callback (logger : logging .Logger ) -> ctypes ._FuncPointer :
68+ def _default_callback (logger : logging .Logger , level : int , message : str ) -> None :
69+ """Default display/forwarding behavior: plain forward into ``logger``."""
70+ logger .log (level , "[CUDA Driver] %s" , message )
71+
72+
73+ def _make_c_callback (logger : logging .Logger , callback : Optional [LogCallback ]) -> ctypes ._FuncPointer :
5574 """Build a ctypes C function pointer that forwards each driver log
56- record to ``logger``.
75+ record to ``logger``, optionally via a user-supplied ``callback`` that
76+ customizes how the message gets displayed.
5777 """
78+ emit = callback if callback is not None else _default_callback
5879
5980 def _on_log (_user_data , log_level , message_ptr , length ):
6081 # This runs inside a ctypes callback trampoline, potentially from a
@@ -63,30 +84,43 @@ def _on_log(_user_data, log_level, message_ptr, length):
6384 raw = ctypes .string_at (message_ptr , length ) if message_ptr else b""
6485 msg = raw .decode ("utf-8" , errors = "replace" ).rstrip ("\n " )
6586 py_level = _CUDA_LEVEL_TO_PY_LEVEL .get (log_level , logging .ERROR )
66- logger . log ( py_level , "[CUDA Driver] %s" , msg )
87+ emit ( logger , py_level , msg )
6788 except Exception :
6889 logger .exception ("cuda_log_bridge: error while forwarding driver log" )
6990
7091 return _CUlogsCallback_functype (_on_log )
7192
7293
73- def register_cuda_log_bridge (logger : logging .Logger | None = None ) -> None :
94+ def register_cuda_log_bridge (
95+ logger : logging .Logger | None = None ,
96+ callback : Optional [LogCallback ] = None ,
97+ ) -> None :
7498 """Register a bridge that forwards CUDA driver ``cuLogs*`` messages to
7599 a Python :class:`logging.Logger`.
76100
77101 This is a process-wide, idempotent operation: the driver only supports
78102 a global log stream (not scoped to a context/stream/thread), so calling
79103 this again while a bridge is already registered is a no-op -- the
80- logger passed to the first call remains in effect.
104+ logger (and callback) passed to the first call remain in effect.
81105
82106 Parameters
83107 ----------
84108 logger : logging.Logger, optional
85109 The logger that driver messages should be forwarded to. Defaults
86110 to ``logging.getLogger("cuda.driver")``.
111+ callback : Callable[[logging.Logger, int, str], None], optional
112+ Customizes how each driver log message is displayed, instead of
113+ being limited to plain forwarding into ``logger``. Called as
114+ ``callback(logger, level, message)`` for every driver log record,
115+ where ``level`` is the mapped ``logging.ERROR``/``logging.WARNING``
116+ level and ``message`` is the decoded driver log text. Defaults to
117+ ``None``, which plainly forwards every message via
118+ ``logger.log(level, "[CUDA Driver] %s", message)``.
87119
88120 Raises
89121 ------
122+ TypeError
123+ If ``callback`` is not ``None`` and not callable.
90124 cuda.core._utils.cuda_utils.CUDAError
91125 If the underlying ``cuLogsRegisterCallback`` call fails, e.g.
92126 because the loaded CUDA driver predates the 12.9 cuLogs* API.
@@ -96,11 +130,14 @@ def register_cuda_log_bridge(logger: logging.Logger | None = None) -> None:
96130 if logger is None :
97131 logger = logging .getLogger ("cuda.driver" )
98132
133+ if callback is not None and not callable (callback ):
134+ raise TypeError (f"callback must be callable or None, got { type (callback )!r} " )
135+
99136 with _lock :
100137 if _callback_handle is not None :
101138 return # already registered; idempotent
102139
103- c_callback = _make_c_callback (logger )
140+ c_callback = _make_c_callback (logger , callback )
104141 addr = ctypes .cast (c_callback , ctypes .c_void_p ).value
105142
106143 handle = handle_return (_driver .cuLogsRegisterCallback (addr , None ))
0 commit comments