Skip to content

Commit 4b9b059

Browse files
committed
pathfinder: add locate_nvidia_dynamic_lib and find_nvidia_dynamic_lib
Return the file load_nvidia_dynamic_lib would load in a fresh process, without loading it into the caller's process. The native loader search runs in the existing subprocess probe. A library already loaded in the current process is not taken into account. Closes #757
1 parent f906024 commit 4b9b059

4 files changed

Lines changed: 359 additions & 4 deletions

File tree

‎cuda_pathfinder/cuda/pathfinder/__init__.py‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,11 @@
1111
find_nvidia_binary_utility as find_nvidia_binary_utility,
1212
)
1313
from cuda.pathfinder._binaries.supported_nvidia_binaries import SUPPORTED_BINARIES as _SUPPORTED_BINARIES
14+
from cuda.pathfinder._dynamic_libs.find_nvidia_dynamic_lib import LocatedDynamicLib as LocatedDynamicLib
15+
from cuda.pathfinder._dynamic_libs.find_nvidia_dynamic_lib import find_nvidia_dynamic_lib as find_nvidia_dynamic_lib
16+
from cuda.pathfinder._dynamic_libs.find_nvidia_dynamic_lib import (
17+
locate_nvidia_dynamic_lib as locate_nvidia_dynamic_lib,
18+
)
1419
from cuda.pathfinder._dynamic_libs.load_dl_common import (
1520
DynamicLibNotAvailableError as DynamicLibNotAvailableError,
1621
)
@@ -76,8 +81,8 @@
7681
SUPPORTED_BINARY_UTILITIES = _SUPPORTED_BINARIES
7782

7883
#: Tuple of CUDA Toolkit dynamic library names supported by
79-
#: :func:`load_nvidia_dynamic_lib` for the current operating system and
80-
#: interpreter architecture.
84+
#: :func:`load_nvidia_dynamic_lib` and :func:`locate_nvidia_dynamic_lib` for
85+
#: the current operating system and interpreter architecture.
8186
SUPPORTED_NVIDIA_LIBNAMES = _SUPPORTED_NVIDIA_LIBNAMES
8287

8388
#: Tuple of supported bitcode library names that can be resolved
Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
from __future__ import annotations
5+
6+
import functools
7+
import os
8+
from dataclasses import dataclass
9+
10+
from cuda.pathfinder._dynamic_libs.lib_descriptor import LIB_DESCRIPTORS
11+
from cuda.pathfinder._dynamic_libs.load_nvidia_dynamic_lib import (
12+
_DRIVER_ONLY_LIBNAMES,
13+
_resolve_system_loaded_abs_path_in_subprocess,
14+
_try_ctk_root_canary,
15+
check_libname,
16+
raise_driver_lib_not_found,
17+
)
18+
from cuda.pathfinder._dynamic_libs.search_steps import (
19+
EARLY_FIND_STEPS,
20+
LATE_FIND_STEPS,
21+
FindResult,
22+
SearchContext,
23+
run_find_steps,
24+
)
25+
26+
27+
@dataclass(frozen=True)
28+
class LocatedDynamicLib:
29+
"""Information about a located dynamic library."""
30+
31+
name: str
32+
abs_path: str
33+
filename: str
34+
found_via: str
35+
36+
37+
def _find_with_system_search(libname: str) -> FindResult | None:
38+
# The native loader search can only be observed by loading, so it runs in
39+
# a fresh subprocess and the caller's process stays untouched.
40+
abs_path = _resolve_system_loaded_abs_path_in_subprocess(libname)
41+
if abs_path is None:
42+
return None
43+
return FindResult(abs_path, "system-search")
44+
45+
46+
def _locate_lib(libname: str) -> FindResult:
47+
desc = LIB_DESCRIPTORS[libname]
48+
49+
if libname in _DRIVER_ONLY_LIBNAMES:
50+
find = _find_with_system_search(libname)
51+
if find is None:
52+
raise_driver_lib_not_found(desc)
53+
return find
54+
55+
ctx = SearchContext(desc)
56+
find = run_find_steps(ctx, EARLY_FIND_STEPS)
57+
if find is not None:
58+
return find
59+
60+
find = _find_with_system_search(libname)
61+
if find is not None:
62+
return find
63+
64+
find = run_find_steps(ctx, LATE_FIND_STEPS)
65+
if find is not None:
66+
return find
67+
68+
if desc.ctk_root_canary_anchor_libnames:
69+
canary_abs_path = _try_ctk_root_canary(ctx)
70+
if canary_abs_path is not None:
71+
return FindResult(canary_abs_path, "system-ctk-root")
72+
73+
ctx.raise_not_found()
74+
75+
76+
def locate_nvidia_dynamic_lib(libname: str) -> LocatedDynamicLib:
77+
"""Locate an NVIDIA dynamic library by name without loading it.
78+
79+
Returns the file that :func:`load_nvidia_dynamic_lib` would load in a fresh
80+
process. Use it where a path is needed but the library must not be loaded
81+
into the current process, for example to pass a library to a build system.
82+
83+
Args:
84+
libname (str): The short name of the library to locate (e.g.,
85+
``"cudart"``, ``"nvvm"``, etc.).
86+
87+
Returns:
88+
LocatedDynamicLib: The absolute path of the library file and how it
89+
was found.
90+
91+
Raises:
92+
DynamicLibUnknownError: If ``libname`` is not a recognized library name.
93+
DynamicLibNotAvailableError: If ``libname`` is recognized but not
94+
supported on this platform.
95+
DynamicLibNotFoundError: If the library cannot be found.
96+
97+
Search order:
98+
The steps of :func:`load_nvidia_dynamic_lib`, in the same order, except
99+
that a library already loaded in the current process is not taken into
100+
account:
101+
102+
1. NVIDIA Python wheels (``site-packages``)
103+
2. Conda environment (``CONDA_PREFIX``)
104+
3. OS default mechanisms (``dlopen()`` / ``LoadLibraryExW()``), run in
105+
a fresh Python subprocess
106+
4. Environment variables (library-specific roots, then ``CUDA_PATH`` /
107+
``CUDA_HOME``)
108+
5. Windows Program Files (configured libraries only)
109+
6. CTK root canary probe (discoverable libs only)
110+
111+
Driver libraries (``"cuda"``, ``"nvml"``) use step 3 only.
112+
113+
Notes:
114+
The result can differ from what :func:`load_nvidia_dynamic_lib` returns
115+
in the current process when another component has already loaded the
116+
library, or influences the native loader search (for example through
117+
its ``RPATH``).
118+
"""
119+
check_libname(libname)
120+
find = _locate_lib(libname)
121+
return LocatedDynamicLib(
122+
name=libname,
123+
abs_path=find.abs_path,
124+
filename=os.path.basename(find.abs_path),
125+
found_via=find.found_via,
126+
)
127+
128+
129+
@functools.cache
130+
def find_nvidia_dynamic_lib(libname: str) -> str:
131+
"""Find the absolute path of an NVIDIA dynamic library without loading it.
132+
133+
See :func:`locate_nvidia_dynamic_lib` for the search order.
134+
135+
Raises:
136+
DynamicLibUnknownError: If ``libname`` is not a recognized library name.
137+
DynamicLibNotAvailableError: If ``libname`` is recognized but not
138+
supported on this platform.
139+
DynamicLibNotFoundError: If the library cannot be found.
140+
"""
141+
return locate_nvidia_dynamic_lib(libname).abs_path

‎cuda_pathfinder/docs/source/api.rst‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66
``cuda.pathfinder`` API Reference
77
=================================
88

9-
The ``cuda.pathfinder`` module provides utilities for loading NVIDIA dynamic libraries,
10-
locating NVIDIA C/C++ header directories, finding CUDA binary utilities, and locating
9+
The ``cuda.pathfinder`` module provides utilities for loading and locating NVIDIA dynamic
10+
libraries, locating NVIDIA C/C++ header directories, finding CUDA binary utilities, and locating
1111
CUDA bitcode and static libraries.
1212

1313
.. NOTE: The source of truth for public APIs is cuda_pathfinder/cuda/pathfinder/__init__.py.
@@ -21,6 +21,9 @@ CUDA bitcode and static libraries.
2121
SUPPORTED_NVIDIA_LIBNAMES
2222
load_nvidia_dynamic_lib
2323
LoadedDL
24+
find_nvidia_dynamic_lib
25+
locate_nvidia_dynamic_lib
26+
LocatedDynamicLib
2427
DynamicLibNotFoundError
2528
DynamicLibUnknownError
2629
DynamicLibNotAvailableError
Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
import os
5+
6+
import pytest
7+
from child_load_nvidia_dynamic_lib_helper import (
8+
build_child_process_failed_for_libname_message,
9+
run_load_nvidia_dynamic_lib_in_subprocess,
10+
)
11+
12+
from cuda.pathfinder import (
13+
DynamicLibNotAvailableError,
14+
DynamicLibNotFoundError,
15+
DynamicLibUnknownError,
16+
LocatedDynamicLib,
17+
find_nvidia_dynamic_lib,
18+
locate_nvidia_dynamic_lib,
19+
)
20+
from cuda.pathfinder._dynamic_libs import find_nvidia_dynamic_lib as find_mod
21+
from cuda.pathfinder._dynamic_libs import load_nvidia_dynamic_lib as load_mod
22+
from cuda.pathfinder._dynamic_libs import supported_nvidia_libs
23+
from cuda.pathfinder._dynamic_libs.load_nvidia_dynamic_lib import _resolve_system_loaded_abs_path_in_subprocess
24+
from cuda.pathfinder._dynamic_libs.search_steps import EARLY_FIND_STEPS, LATE_FIND_STEPS, FindResult
25+
from cuda.pathfinder._dynamic_libs.subprocess_protocol import STATUS_NOT_FOUND, parse_dynamic_lib_subprocess_payload
26+
from cuda.pathfinder._utils.platform_aware import IS_WINDOWS, quote_for_shell
27+
28+
_MODULE = "cuda.pathfinder._dynamic_libs.find_nvidia_dynamic_lib"
29+
30+
31+
@pytest.fixture(autouse=True)
32+
def _clear_caches():
33+
find_nvidia_dynamic_lib.cache_clear()
34+
_resolve_system_loaded_abs_path_in_subprocess.cache_clear()
35+
yield
36+
find_nvidia_dynamic_lib.cache_clear()
37+
_resolve_system_loaded_abs_path_in_subprocess.cache_clear()
38+
39+
40+
@pytest.fixture
41+
def no_in_process_loading(mocker):
42+
for name in ("check_if_already_loaded_from_elsewhere", "load_with_system_search", "load_with_abs_path"):
43+
mocker.patch.object(load_mod.LOADER, name, side_effect=AssertionError(f"LOADER.{name} was called"))
44+
45+
46+
def _patch_find_steps(mocker, *, early=None, late=None):
47+
def run_find_steps(_ctx, steps):
48+
if steps is EARLY_FIND_STEPS:
49+
return early
50+
assert steps is LATE_FIND_STEPS
51+
return late
52+
53+
return mocker.patch(f"{_MODULE}.run_find_steps", side_effect=run_find_steps)
54+
55+
56+
@pytest.mark.parametrize(
57+
"libname",
58+
supported_nvidia_libs.SUPPORTED_WINDOWS_DLLS if IS_WINDOWS else supported_nvidia_libs.SUPPORTED_LINUX_SONAMES,
59+
)
60+
@pytest.mark.agent_authored(model="claude-opus-5-5")
61+
def test_locate_matches_load_in_fresh_process(info_summary_append, libname):
62+
timeout = 120 if IS_WINDOWS else 30
63+
result = run_load_nvidia_dynamic_lib_in_subprocess(libname, timeout=timeout)
64+
if result.returncode != 0:
65+
raise RuntimeError(build_child_process_failed_for_libname_message(libname, result))
66+
payload = parse_dynamic_lib_subprocess_payload(
67+
result.stdout,
68+
libname=libname,
69+
error_label="Load subprocess child process",
70+
)
71+
72+
if payload.status == STATUS_NOT_FOUND:
73+
with pytest.raises(DynamicLibNotFoundError):
74+
locate_nvidia_dynamic_lib(libname)
75+
info_summary_append(f"Not found: {libname=!r}")
76+
return
77+
78+
located = locate_nvidia_dynamic_lib(libname)
79+
info_summary_append(f"abs_path={quote_for_shell(located.abs_path)} found_via={located.found_via}")
80+
assert located.name == libname
81+
assert located.filename == os.path.basename(located.abs_path)
82+
assert os.path.samefile(located.abs_path, payload.abs_path)
83+
assert find_nvidia_dynamic_lib(libname) == located.abs_path
84+
85+
86+
@pytest.mark.usefixtures("no_in_process_loading")
87+
@pytest.mark.agent_authored(model="claude-opus-5-5")
88+
def test_early_find_skips_system_search(mocker, tmp_path):
89+
lib = tmp_path / "libcudart.so.13"
90+
_patch_find_steps(mocker, early=FindResult(str(lib), "site-packages"))
91+
probe = mocker.patch(f"{_MODULE}._resolve_system_loaded_abs_path_in_subprocess")
92+
93+
assert locate_nvidia_dynamic_lib("cudart") == LocatedDynamicLib(
94+
name="cudart",
95+
abs_path=str(lib),
96+
filename="libcudart.so.13",
97+
found_via="site-packages",
98+
)
99+
probe.assert_not_called()
100+
101+
102+
@pytest.mark.usefixtures("no_in_process_loading")
103+
@pytest.mark.agent_authored(model="claude-opus-5-5")
104+
def test_system_search_runs_before_late_find_steps(mocker, tmp_path):
105+
lib = tmp_path / "libcudart.so.13"
106+
run_find_steps = _patch_find_steps(mocker, late=FindResult("unused", "CUDA_PATH"))
107+
probe = mocker.patch(f"{_MODULE}._resolve_system_loaded_abs_path_in_subprocess", return_value=str(lib))
108+
109+
located = locate_nvidia_dynamic_lib("cudart")
110+
111+
assert located.abs_path == str(lib)
112+
assert located.found_via == "system-search"
113+
probe.assert_called_once_with("cudart")
114+
assert [call.args[1] for call in run_find_steps.call_args_list] == [EARLY_FIND_STEPS]
115+
116+
117+
@pytest.mark.usefixtures("no_in_process_loading")
118+
@pytest.mark.agent_authored(model="claude-opus-5-5")
119+
def test_late_find_steps_after_system_search(mocker, tmp_path):
120+
lib = tmp_path / "libcudart.so.13"
121+
_patch_find_steps(mocker, late=FindResult(str(lib), "CUDA_PATH"))
122+
mocker.patch(f"{_MODULE}._resolve_system_loaded_abs_path_in_subprocess", return_value=None)
123+
124+
located = locate_nvidia_dynamic_lib("cudart")
125+
126+
assert located.abs_path == str(lib)
127+
assert located.found_via == "CUDA_PATH"
128+
129+
130+
@pytest.mark.usefixtures("no_in_process_loading")
131+
@pytest.mark.agent_authored(model="claude-opus-5-5")
132+
def test_ctk_root_canary_is_last(mocker, tmp_path):
133+
lib = tmp_path / "libnvvm.so.4"
134+
_patch_find_steps(mocker)
135+
mocker.patch(f"{_MODULE}._resolve_system_loaded_abs_path_in_subprocess", return_value=None)
136+
canary = mocker.patch(f"{_MODULE}._try_ctk_root_canary", return_value=str(lib))
137+
138+
located = locate_nvidia_dynamic_lib("nvvm")
139+
140+
assert located.abs_path == str(lib)
141+
assert located.found_via == "system-ctk-root"
142+
canary.assert_called_once()
143+
144+
145+
@pytest.mark.usefixtures("no_in_process_loading")
146+
@pytest.mark.agent_authored(model="claude-opus-5-5")
147+
def test_not_found_raises(mocker):
148+
_patch_find_steps(mocker)
149+
mocker.patch(f"{_MODULE}._resolve_system_loaded_abs_path_in_subprocess", return_value=None)
150+
mocker.patch(f"{_MODULE}._try_ctk_root_canary", return_value=None)
151+
152+
with pytest.raises(DynamicLibNotFoundError, match="Failure finding"):
153+
locate_nvidia_dynamic_lib("nvvm")
154+
with pytest.raises(DynamicLibNotFoundError, match="Failure finding"):
155+
find_nvidia_dynamic_lib("nvvm")
156+
157+
158+
@pytest.mark.usefixtures("no_in_process_loading")
159+
@pytest.mark.agent_authored(model="claude-opus-5-5")
160+
def test_driver_lib_uses_system_search_only(mocker, tmp_path):
161+
lib = tmp_path / "libcuda.so.1"
162+
run_find_steps = mocker.patch(f"{_MODULE}.run_find_steps")
163+
mocker.patch(f"{_MODULE}._resolve_system_loaded_abs_path_in_subprocess", return_value=str(lib))
164+
165+
located = locate_nvidia_dynamic_lib("cuda")
166+
167+
assert located.abs_path == str(lib)
168+
assert located.found_via == "system-search"
169+
run_find_steps.assert_not_called()
170+
171+
172+
@pytest.mark.usefixtures("no_in_process_loading")
173+
@pytest.mark.agent_authored(model="claude-opus-5-5")
174+
def test_driver_lib_not_found_raises(mocker):
175+
mocker.patch(f"{_MODULE}._resolve_system_loaded_abs_path_in_subprocess", return_value=None)
176+
177+
with pytest.raises(DynamicLibNotFoundError, match="NVIDIA driver library"):
178+
locate_nvidia_dynamic_lib("cuda")
179+
180+
181+
@pytest.mark.agent_authored(model="claude-opus-5-5")
182+
def test_find_is_cached(mocker, tmp_path):
183+
lib = tmp_path / "libcudart.so.13"
184+
locate = mocker.patch(
185+
f"{_MODULE}.locate_nvidia_dynamic_lib",
186+
return_value=LocatedDynamicLib("cudart", str(lib), lib.name, "site-packages"),
187+
)
188+
189+
assert find_mod.find_nvidia_dynamic_lib("cudart") == str(lib)
190+
assert find_mod.find_nvidia_dynamic_lib("cudart") == str(lib)
191+
locate.assert_called_once_with("cudart")
192+
193+
194+
@pytest.mark.agent_authored(model="claude-opus-5-5")
195+
def test_unknown_libname_raises_dynamic_lib_unknown_error():
196+
with pytest.raises(DynamicLibUnknownError, match=r"Unknown library name: 'not_a_real_lib'"):
197+
locate_nvidia_dynamic_lib("not_a_real_lib")
198+
199+
200+
@pytest.mark.agent_authored(model="claude-opus-5-5")
201+
def test_known_but_platform_unavailable_libname_raises_dynamic_lib_not_available_error(monkeypatch):
202+
monkeypatch.setattr(load_mod, "_ALL_KNOWN_LIBNAMES", frozenset(("known_but_unavailable",)))
203+
monkeypatch.setattr(load_mod, "ALL_AVAILABLE_LIBNAMES", frozenset())
204+
monkeypatch.setattr(load_mod, "_PLATFORM_NAME", "TestOS")
205+
with pytest.raises(DynamicLibNotAvailableError, match=r"known_but_unavailable.*not available on TestOS"):
206+
locate_nvidia_dynamic_lib("known_but_unavailable")

0 commit comments

Comments
 (0)