GPU 0.2.0: @Gpu path, GpuArena, workgroup barriers, docs, and cthreads[gpu] wheels

.clangd

@@ -0,0 +1,20 @@
+# clangd config for cthreads (Cursor / VS Code clangd).
+# Paths are relative to this file (repo root), except Vulkan SDK.
+
+CompileFlags:
+  Add:
+    - -std=c++17
+    # Match CMake CTHREADS_GPU=ON so #ifdef CTHREADS_WITH_GPU paths analyze correctly.
+    - -DCTHREADS_WITH_GPU=1
+    # Project includes (same as CMake target_include_directories for GPU builds).
+    - -Isrc/cthreads/cpp/headers
+    - -Isrc/cthreads/cpp/gpu/headers
+    # Vulkan headers from local SDK (VULKAN_SDK=C:\VulkanSDK\1.4.357.0).
+    # Update this -I if you install a newer SDK version.
+    - -IC:/VulkanSDK/1.4.357.0/Include
+
+Diagnostics:
+  UnusedIncludes: None
+
+Index:
+  Background: Build

.github/workflows/ci.yml

@@ -36,3 +36,58 @@ jobs:
 
       - name: Pytest
         run: python -m pytest tests/ -q
+
+  # Compile-smokes the Vulkan path (CTHREADS_GPU=ON). Live device tests still skip
+  # when no ICD is present; the goal is to catch header / glslang / link breakage.
+  test-gpu:
+    name: test-gpu (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install Vulkan headers (Ubuntu)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libvulkan-dev vulkan-tools
+
+      - name: Install Vulkan SDK (Windows)
+        if: runner.os == 'Windows'
+        uses: humbletim/setup-vulkan-sdk@v1.2.1
+        with:
+          vulkan-query-version: 1.3.296.0
+          vulkan-components: Vulkan-Headers, Vulkan-Loader
+          vulkan-use-cache: true
+
+      - name: Install CMake, Ninja, package (GPU ON, Linux)
+        if: runner.os == 'Linux'
+        run: |
+          python -m pip install -U pip
+          python -m pip install cmake ninja
+          export CMAKE_ARGS="-DCTHREADS_GPU=ON"
+          python -m pip install -e ".[test]"
+
+      - name: Install CMake, Ninja, package (GPU ON, Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          python -m pip install -U pip
+          python -m pip install cmake ninja
+          $env:CMAKE_ARGS = "-DCTHREADS_GPU=ON"
+          python -m pip install -e ".[test]"
+
+      - name: Assert GPU extension linked
+        run: |
+          python -c "from cthreads import _ext, gpu; assert hasattr(_ext, 'gpu'), 'CTHREADS_GPU build missing _ext.gpu'; print('available=', gpu.available())"
+
+      - name: Pytest (GPU build; device tests skip if no ICD)
+        run: python -m pytest tests/ -q

.github/workflows/release.yml

@@ -2,6 +2,11 @@ name: Release
 
 # Production PyPI: only when you click Publish on a GitHub Release.
 # Manual "Run workflow" always targets TestPyPI, never PyPI.
+#
+# Artifacts:
+#   - cthreads          CPU wheels + sdist  (CTHREADS_GPU=OFF)
+#   - cthreads-gpu      GPU wheels          (CTHREADS_GPU=ON)
+# Users: pip install cthreads  OR  pip install 'cthreads[gpu]'  (pulls cthreads-gpu)
 
 on:
   release:
@@ -28,6 +33,32 @@ jobs:
           python -m pip install -e ".[test]"
           python -m pytest tests/ -q
 
+  test-gpu:
+    name: test-gpu (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Vulkan headers
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libvulkan-dev
+
+      - name: Install and test (GPU ON)
+        run: |
+          python -m pip install -U pip cmake ninja
+          export CMAKE_ARGS="-DCTHREADS_GPU=ON"
+          python -m pip install -e ".[test]"
+          python - <<'PY'
+          from cthreads import _ext
+          assert hasattr(_ext, "gpu"), "CTHREADS_GPU build missing _ext.gpu"
+          PY
+          python -m pytest tests/ -q
+
   check-version:
     name: tag matches pyproject
     if: github.event_name == 'release'
@@ -37,22 +68,34 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - name: Compare release tag to project.version
+      - name: Compare release tag to project.version and [gpu] pin
         env:
           TAG: ${{ github.event.release.tag_name }}
         run: |
           python - <<'PY'
           import os
           import pathlib
+          import re
           import sys
           import tomllib
 
           tag = os.environ["TAG"].removeprefix("v")
-          ver = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))["project"]["version"]
+          text = pathlib.Path("pyproject.toml").read_text(encoding="utf-8")
+          ver = tomllib.loads(text)["project"]["version"]
           if tag != ver:
               print(f"GitHub tag version {tag!r} != pyproject.toml version {ver!r}")
               sys.exit(1)
-          print(f"version ok: {ver}")
+          m = re.search(r'gpu\s*=\s*\["cthreads-gpu==([^"]+)"\]', text)
+          if not m:
+              print("missing [project.optional-dependencies] gpu = [\"cthreads-gpu==...\"]")
+              sys.exit(1)
+          if m.group(1) != ver:
+              print(
+                  f"optional gpu pin cthreads-gpu=={m.group(1)!r} "
+                  f"!= project.version {ver!r}"
+              )
+              sys.exit(1)
+          print(f"version ok: {ver} (gpu extra pin matches)")
           PY
 
   build-sdist:
@@ -74,7 +117,7 @@ jobs:
           path: dist/*.tar.gz
 
   build-wheels:
-    name: wheels (${{ matrix.os }})
+    name: wheels-cpu (${{ matrix.os }})
     needs: [test]
     runs-on: ${{ matrix.os }}
     strategy:
@@ -83,16 +126,70 @@ jobs:
         os: [ubuntu-latest, windows-latest]
     steps:
       - uses: actions/checkout@v4
-      - name: Build wheels
+      - name: Build CPU wheels
         uses: pypa/cibuildwheel@v4.2.0
       - uses: actions/upload-artifact@v4
         with:
           name: cibw-wheels-${{ matrix.os }}
           path: wheelhouse/*.whl
 
+  build-wheels-gpu:
+    name: wheels-gpu (${{ matrix.os }})
+    needs: [test-gpu]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Vulkan headers (Ubuntu host; manylinux uses before-all)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libvulkan-dev
+
+      - name: Install Vulkan SDK (Windows)
+        if: runner.os == 'Windows'
+        uses: humbletim/setup-vulkan-sdk@v1.2.1
+        with:
+          vulkan-query-version: 1.3.296.0
+          vulkan-components: Vulkan-Headers, Vulkan-Loader
+          vulkan-use-cache: true
+
+      - name: Retarget project name to cthreads-gpu
+        run: python scripts/retarget_gpu_wheel.py
+
+      - name: Build GPU wheels
+        uses: pypa/cibuildwheel@v4.2.0
+        env:
+          # Headers only at build time; loader is resolved at runtime.
+          CIBW_ENVIRONMENT: CMAKE_ARGS=-DCTHREADS_GPU=ON
+          CIBW_BEFORE_ALL_LINUX: |
+            set -eux
+            if command -v dnf >/dev/null 2>&1; then
+              dnf install -y vulkan-headers vulkan-loader-devel git
+            else
+              yum install -y vulkan-headers vulkan-loader-devel git
+            fi
+          # glslang FetchContent makes this slower than CPU wheels.
+          CIBW_BUILD_VERBOSITY: 1
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-gpu-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
   publish-pypi:
     name: publish to PyPI
-    needs: [test, check-version, build-sdist, build-wheels]
+    needs:
+      - test
+      - test-gpu
+      - check-version
+      - build-sdist
+      - build-wheels
+      - build-wheels-gpu
     if: github.event_name == 'release' && github.event.action == 'published'
     runs-on: ubuntu-latest
     environment:
@@ -106,11 +203,20 @@ jobs:
           pattern: cibw-*
           path: dist
           merge-multiple: true
+      - name: Show artifacts
+        run: ls -la dist
+      # Uploads both cthreads and cthreads-gpu wheels. Configure Trusted
+      # Publishing for BOTH PyPI projects (same workflow: release.yml).
       - uses: pypa/gh-action-pypi-publish@release/v1
 
   publish-testpypi:
     name: publish to TestPyPI
-    needs: [test, build-sdist, build-wheels]
+    needs:
+      - test
+      - test-gpu
+      - build-sdist
+      - build-wheels
+      - build-wheels-gpu
     if: github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     environment:
@@ -124,6 +230,8 @@ jobs:
           pattern: cibw-*
           path: dist
           merge-multiple: true
+      - name: Show artifacts
+        run: ls -la dist
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/

.gitignore

@@ -17,6 +17,7 @@ dist/
 *.dylib
 .cthreads_cache.json
 .pytest_cache/
+.vscode/
 
 # CMake / MSVC litter - must never land in the source tree
 src/cthreads/cpp/CMakeCache.txt
@@ -51,6 +52,7 @@ api/
 # >>> cthreads (auto)
 __Thread__/
 __Threadable__/
+__Gpu__/
 .cthreads_cache.json
 cthreads_kernels.dll
 cthreads_kernels.so
@@ -59,4 +61,6 @@ libcthreads_kernels.so
 libcthreads_kernels.dylib
 # <<< cthreads (auto)
 
-todo.md
+todo.md
+# demo artifacts
+*.gif