Support for free-threaded build of CPython

.github/get-py-env.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+#
+# Determine info about the Python install and write shell code to stdout, to
+# set env variables.  This will set the variables PY_LDFLAGS, PY_CFLAGS and
+# PY_INC_PATH.
+#
+# The python3-config tool is used as the source of this info. In theory we
+# could use sysconfig as well but the setup-python action from github appears
+# to patch python3-config but not patch the sysconfig info.
+#
+# Usage:
+#   eval $(python3 get-py-env.py)
+
+import os
+import re
+import subprocess
+
+
+def get_output(cmd):
+    rv = subprocess.run(
+        cmd,
+        capture_output=True,  # Capture stdout and stderr
+        text=True,  # Decode output as text (UTF-8)
+        check=True,  # Raise an error if the command fails
+    )
+    return rv.stdout
+
+
+def extract_flags(cmd, prefix):
+    flags = []
+    for part in get_output(cmd).split():
+        part = part.strip()
+        if part.startswith(prefix):
+            flags.append(part)
+    return ' '.join(flags)
+
+
+def find_python_h():
+    """Find the include path that has Python.h contained inside.
+    We could use INCLUDEPY from sysconfig but github patches
+    python3-config but not the sysconfig info (after moving the
+    install).
+    """
+    c_flags = extract_flags(['python3-config', '--cflags'], '-I')
+    for part in c_flags.split():
+        m = re.search(r'-I(\S+)', part)
+        if not m:
+            continue
+        inc_path = m.group(1)
+        if os.path.exists(os.path.join(inc_path, 'Python.h')):
+            return inc_path
+    raise SystemExit('cannot find Python.h')
+
+
+def main():
+    ld_flags = extract_flags(['python3-config', '--ldflags'], '-L')
+    c_flags = extract_flags(['python3-config', '--cflags'], '-I')
+    include_path = find_python_h()
+    print(f'PY_LDFLAGS="{ld_flags}"')
+    print(f'PY_CFLAGS="{c_flags}"')
+    print(f'PY_INC_PATH="{include_path}"')
+
+
+if __name__ == '__main__':
+    main()

.github/run-faber.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+
+set -eu
+
+echo "cxx version: $CXX $($CXX --version)"
+echo "cxx std: $CXX_STD"
+echo "python3 path: $(which python3)"
+echo "python3 version: $(python3 --version)"
+
+if ! which faber > /dev/null; then
+    echo "Installing faber..."
+    python3 -m pip install --upgrade pip
+    python3 -m pip install -U faber
+fi
+echo "faber version: $(faber -v)"
+
+# find and set PY_LDFLAGS and PY_INC_PATH
+eval $(python3 .github/get-py-env.py)
+
+echo "PY_INC_PATH=$PY_INC_PATH"
+echo "PY_LDFLAGS=$PY_LDFLAGS"
+
+case $(python3-config --abiflags) in
+    *t*)
+        # When running with free-threaded, we always want to disable the GIL
+        # even for extensions without the mod_gil_not_used() flag
+        export PYTHON_GIL=0
+        ;;
+esac
+
+# this could be set by LD_LIBRARY_PATH but faber overrides it
+prefix=$(python3-config --prefix)
+echo "${prefix}/lib" > /etc/ld.so.conf.d/boost-ci.conf && ldconfig
+
+sed -e "s/\$PYTHON/python3/g" .ci/faber > $HOME/.faber
+
+faber \
+  --with-boost-include=${BOOST_PY_DEPS} \
+  --builddir=build \
+  cxx.name="${CXX}" \
+  cxxflags="-std=${CXX_STD}" \
+  cppflags="-std=${CXX_STD}" \
+  include="${PY_INC_PATH}" \
+  ldflags="${PY_LDFLAGS}" \
+  -j`nproc` \
+  "$@"

.github/workflows/test-ubuntu-py2.yml

@@ -0,0 +1,58 @@
+name: Test Ubuntu, Python 2.x
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python: [python]
+        cxx: [g++]
+        std: [c++11]
+        include:
+          # Add the appropriate docker image for each compiler.
+          # The images from teeks99/boost-python-test already have boost::python
+          # pre-reqs installed, see:
+          # https://github.com/teeks99/boost-python-test-docker
+          - cxx: g++
+            docker-img: teeks99/boost-python-test:gcc-15_1.89.0
+
+    container:
+      image: ${{ matrix.docker-img }}
+
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: setup prerequisites
+      run: |
+        # Warning: this is not necessarily the same Python version as the one configured above !
+        python3 -m pip install -U faber --break-system-packages
+    - name: build
+      run: |
+        ${{ matrix.python }} --version
+        ${{ matrix.cxx }} --version
+        faber -v
+        sed -e "s/\$PYTHON/${{ matrix.python }}/g" .ci/faber > ~/.faber
+        faber \
+          --with-boost-include=${BOOST_PY_DEPS} \
+          --builddir=build \
+          cxx.name=${{ matrix.cxx }} \
+          cxxflags=-std=${{ matrix.std }} \
+          cppflags=-std=${{ matrix.std }} \
+          -j`nproc`
+    - name: test
+      run: |
+        faber \
+          --with-boost-include=${BOOST_PY_DEPS} \
+          --builddir=build \
+          cxx.name=${{ matrix.cxx }} \
+          cxxflags=-std=${{ matrix.std }} \
+          cppflags=-std=${{ matrix.std }} \
+          -j`nproc` \
+          test.report

.github/workflows/test-ubuntu.yml

@@ -1,6 +1,10 @@
+# Test on Ubuntu with various compiler and language standard versions.
 name: Test Ubuntu
 
-on:  [push, pull_request]
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
 
 jobs:
   build:
@@ -9,49 +13,37 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python: [python, python3]
+        python-version: ['3.14']
         cxx: [g++, clang++]
         std: [c++11, c++14, c++17]
         include:
-          # Add the appropriate docker image for each compiler.
-          # The images from teeks99/boost-python-test already have boost::python
-          # pre-reqs installed, see:
-          # https://github.com/teeks99/boost-python-test-docker
-          - cxx: clang++
-            docker-img: teeks99/boost-python-test:clang-21_1.89.0
-          - cxx: g++
-            docker-img: teeks99/boost-python-test:gcc-15_1.89.0
+          # Also test with free-threaded build of Python
+          - python-version: '3.14t'
+            cxx: clang++
+            std: c++17
 
     container:
-      image: ${{ matrix.docker-img }}
+      # Add the appropriate docker image for the compiler.
+      # The images from teeks99/boost-python-test already have boost::python
+      # pre-reqs installed, see:
+      # https://github.com/teeks99/boost-python-test-docker
+      image: ${{ matrix.cxx == 'g++' &&
+        'teeks99/boost-python-test:gcc-15_1.89.0' ||
+        'teeks99/boost-python-test:clang-21_1.89.0' }}
 
     steps:
     - uses: actions/checkout@v5
-
+    - name: setup python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
     - name: setup prerequisites
       run: |
-        # Warning: this is not necessarily the same Python version as the one configured above !
-        python3 -m pip install -U faber --break-system-packages
+        echo "CXX=${{ matrix.cxx }}" >> "$GITHUB_ENV"
+        echo "CXX_STD=${{ matrix.std }}" >> "$GITHUB_ENV"
     - name: build
       run: |
-        ${{ matrix.python }} --version
-        ${{ matrix.cxx }} --version
-        faber -v
-        sed -e "s/\$PYTHON/${{ matrix.python }}/g" .ci/faber > ~/.faber
-        faber \
-          --with-boost-include=${BOOST_PY_DEPS} \
-          --builddir=build \
-          cxx.name=${{ matrix.cxx }} \
-          cxxflags=-std=${{ matrix.std }} \
-          cppflags=-std=${{ matrix.std }} \
-          -j`nproc`
+        .github/run-faber.sh
     - name: test
       run: |
-        faber \
-          --with-boost-include=${BOOST_PY_DEPS} \
-          --builddir=build \
-          cxx.name=${{ matrix.cxx }} \
-          cxxflags=-std=${{ matrix.std }} \
-          cppflags=-std=${{ matrix.std }} \
-          -j`nproc` \
-          test.report
+        .github/run-faber.sh test.report

include/boost/python/detail/pymutex.hpp

@@ -0,0 +1,103 @@
+// Copyright 2025 Boost.Python Contributors
+// Distributed under the Boost Software License, Version 1.0. (See
+// accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+
+#ifndef BOOST_PYTHON_DETAIL_PYMUTEX_HPP
+#define BOOST_PYTHON_DETAIL_PYMUTEX_HPP
+
+#include <boost/python/detail/prefix.hpp>
+#ifdef Py_GIL_DISABLED
+// needed for pymutex wrapper
+#include <atomic>
+#include <cstddef>
+#endif
+
+namespace boost { namespace python { namespace detail {
+
+#ifdef Py_GIL_DISABLED
+
+// Re-entrant wrapper around PyMutex for free-threaded Python
+// Similar to _PyRecursiveMutex or threading.RLock
+class pymutex {
+    PyMutex m_mutex;
+    std::atomic<unsigned long> m_owner;
+    std::size_t m_level;
+
+public:
+    pymutex() : m_mutex({}), m_owner(0), m_level(0) {}
+
+    // Non-copyable, non-movable
+    pymutex(const pymutex&) = delete;
+    pymutex& operator=(const pymutex&) = delete;
+
+    void lock() {
+        unsigned long thread = PyThread_get_thread_ident();
+        if (m_owner.load(std::memory_order_relaxed) == thread) {
+            m_level++;
+            return;
+        }
+        PyMutex_Lock(&m_mutex);
+        m_owner.store(thread, std::memory_order_relaxed);
+        // m_level should be 0 when we acquire the lock
+    }
+
+    void unlock() {
+        unsigned long thread = PyThread_get_thread_ident();
+        // Verify current thread owns the lock
+        if (m_owner.load(std::memory_order_relaxed) != thread) {
+            // This should never happen - programming error
+            return;
+        }
+        if (m_level > 0) {
+            m_level--;
+            return;
+        }
+        m_owner.store(0, std::memory_order_relaxed);
+        PyMutex_Unlock(&m_mutex);
+    }
+
+    bool is_locked_by_current_thread() const {
+        unsigned long thread = PyThread_get_thread_ident();
+        return m_owner.load(std::memory_order_relaxed) == thread;
+    }
+};
+
+
+// RAII lock guard for pymutex
+class pymutex_guard {
+    pymutex& m_mutex;
+
+public:
+    explicit pymutex_guard(pymutex& mutex) : m_mutex(mutex) {
+        m_mutex.lock();
+    }
+
+    ~pymutex_guard() {
+        m_mutex.unlock();
+    }
+
+    // Non-copyable, non-movable
+    pymutex_guard(const pymutex_guard&) = delete;
+    pymutex_guard& operator=(const pymutex_guard&) = delete;
+};
+
+// Global mutex for protecting all Boost.Python internal state
+// Similar to pybind11's internals.mutex
+BOOST_PYTHON_DECL pymutex& get_global_mutex();
+
+// Macro for acquiring the global lock
+// Similar to pybind11's PYBIND11_LOCK_INTERNALS
+#define BOOST_PYTHON_LOCK_STATE() \
+    ::boost::python::detail::pymutex_guard lock(::boost::python::detail::get_global_mutex())
+
+#else
+
+// No-op macro when not in free-threaded mode
+#define BOOST_PYTHON_LOCK_STATE()
+
+#endif // Py_GIL_DISABLED
+
+}}} // namespace boost::python::detail
+
+#endif // BOOST_PYTHON_DETAIL_PYMUTEX_HPP