Fix handling of duplicate _PyRuntime symbols when libraries dlopen Python

When libraries like llvmlite dlopen the Python binary, it creates duplicate
mappings of the binary in the process memory. This caused pystack to use the
wrong address for _PyRuntime, leading to "Invalid address in remote process" errors.

The fix ensures we use the first (lowest address) mapping found, which is
typically the original/correct one, rather than overwriting with later mappings.

Fixes #255

Author: pablogsal

requirements-test.txt

@@ -4,3 +4,4 @@ pytest
 pytest-cov
 pytest-xdist
 setuptools
+llvmlite ; sys_platform == "linux"

src/pystack/_pystack/unwinder.cpp

@@ -375,9 +375,16 @@ module_callback(
     for (int i = 0; i < n_syms; i++) {
         const char* sname = dwfl_module_getsym_info(mod, i, &sym, &addr, nullptr, nullptr, nullptr);
         if (strcmp(sname, module_arg->symbol) == 0) {
-            module_arg->addr = addr;
-            LOG(INFO) << "Symbol '" << sname << "' found at address " << std::hex << std::showbase
-                      << addr;
+            // Only update the address if we haven't found it yet, or if this is a lower address
+            // (the first/original mapping is typically at a lower address than dlopened copies)
+            if (module_arg->addr == 0 || addr < module_arg->addr) {
+                module_arg->addr = addr;
+                LOG(INFO) << "Symbol '" << sname << "' found at address " << std::hex << std::showbase
+                          << addr;
+            } else {
+                LOG(INFO) << "Symbol '" << sname << "' found at address " << std::hex << std::showbase
+                          << addr << " but keeping previously found address " << module_arg->addr;
+            }
             break;
         }
     }

tests/integration/llvmlite_program.py

@@ -0,0 +1,26 @@
+import sys
+import time
+
+
+def first_func():
+    second_func()
+
+
+def second_func():
+    third_func()
+
+
+def third_func():
+    # Try to import llvmlite which can dlopen the Python binary
+    try:
+        print("llvmlite imported", file=sys.stderr)
+    except ImportError:
+        print("llvmlite not available", file=sys.stderr)
+
+    fifo = sys.argv[1]
+    with open(sys.argv[1], "w") as fifo:
+        fifo.write("ready")
+    time.sleep(1000)
+
+
+first_func()

tests/integration/test_shenanigans.py

@@ -0,0 +1,43 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+from pystack.engine import get_process_threads
+from tests.utils import spawn_child_process
+from tests.utils import xfail_on_expected_exceptions
+
+
+TEST_DUPLICATE_SYMBOLS_FILE = Path(__file__).parent / "llvmlite_program.py"
+
+
+@pytest.mark.skipif(sys.platform != "linux", reason="Linux-specific dlopen behavior")
+def test_duplicate_pyruntime_symbol_handling(tmpdir):
+    """Test that pystack correctly handles duplicate _PyRuntime symbols.
+
+    This can occur when libraries like llvmlite dlopen the Python binary,
+    creating duplicate mappings. The fix ensures we use the first (lowest address)
+    mapping which is typically the correct one.
+    """
+    # WHEN
+    with spawn_child_process(
+        sys.executable, TEST_DUPLICATE_SYMBOLS_FILE, tmpdir
+    ) as child_process:
+        threads = list(
+            get_process_threads(
+                child_process.pid, stop_process=True
+            )
+        )
+
+    # THEN
+    # We should have successfully resolved threads without "Invalid address" errors
+    assert threads is not None
+    assert len(threads) > 0
+
+    # Verify we can get stack traces (which requires correct _PyRuntime)
+    for thread in threads:
+        # Just ensure we can get frames without crashing
+        frames = list(thread.frames)
+        # The main thread should have at least one frame
+        if thread.tid == child_process.pid:
+            assert len(frames) > 0