Publish OpenCL compute helpers and improved examples

.github/workflows/test.yml

@@ -57,7 +57,8 @@ jobs:
       - name: Assemble namespaced module and install example modules
         run: |
           install -d "$HOME/.vmodules/antono2/opencl"
-          install -m 0644 opencl.v convenience.v ownership.v program.v event.v image.v svm.v capabilities.v external_interop.v v.mod VERSION LICENSE GENERATOR_COMMIT "$HOME/.vmodules/antono2/opencl/"
+          cp *.v v.mod VERSION LICENSE GENERATOR_COMMIT "$HOME/.vmodules/antono2/opencl/"
+          cp -R include algorithms "$HOME/.vmodules/antono2/opencl/"
           install -d "$HOME/.vmodules/antono2/opencl/include/CL"
           install -m 0644 include/CL/opencl.h "$HOME/.vmodules/antono2/opencl/include/CL/opencl.h"
           test "$(git -C .ci-modules/vulkan describe --tags --exact-match)" = '${{ steps.compat.outputs.module_vulkan }}'
@@ -70,6 +71,11 @@ jobs:
           v -cc gcc run test
           v test convenience_test.v
           v test test/pointer_abi_test.v
+          python3 tools/check_docs.py
+          v -cc gcc run examples/getting_started
+          v -cc gcc test test/helpers_test.v
+          v -cc gcc -d opencl_dynamic test test/helpers_test.v
+          python3 test/test_dynamic_runtime.py
           v -cc gcc run examples/vector_add
           v -cc gcc run examples/image_svm
       - name: Build and test Vulkan particles example
@@ -111,13 +117,15 @@ jobs:
       - name: Assemble namespaced module
         run: |
           install -d "$HOME/.vmodules/antono2/opencl"
-          install -m 0644 opencl.v convenience.v ownership.v program.v event.v image.v svm.v capabilities.v external_interop.v v.mod VERSION LICENSE GENERATOR_COMMIT "$HOME/.vmodules/antono2/opencl/"
+          cp *.v v.mod VERSION LICENSE GENERATOR_COMMIT "$HOME/.vmodules/antono2/opencl/"
+          cp -R include algorithms "$HOME/.vmodules/antono2/opencl/"
           install -d "$HOME/.vmodules/antono2/opencl/include/CL"
           install -m 0644 include/CL/opencl.h "$HOME/.vmodules/antono2/opencl/include/CL/opencl.h"
       - name: Compile macOS ABI probe
         run: |
           v run setup.vsh --check
           v -cc clang -o /tmp/opencl-abi-probe abi/main.c.v
+          v -cc clang -d opencl_dynamic -o /tmp/opencl-dynamic-probe examples/getting_started
 
   linux-v-master:
     runs-on: ubuntu-24.04
@@ -157,7 +165,8 @@ jobs:
         if: steps.setup_v_master.outcome == 'success'
         run: |
           install -d "$HOME/.vmodules/antono2/opencl"
-          install -m 0644 opencl.v convenience.v ownership.v program.v event.v image.v svm.v capabilities.v external_interop.v v.mod VERSION LICENSE GENERATOR_COMMIT "$HOME/.vmodules/antono2/opencl/"
+          cp *.v v.mod VERSION LICENSE GENERATOR_COMMIT "$HOME/.vmodules/antono2/opencl/"
+          cp -R include algorithms "$HOME/.vmodules/antono2/opencl/"
       - name: Run correctness smoke tests on V master
         id: test_v_master
         if: steps.setup_v_master.outcome == 'success'
@@ -217,10 +226,12 @@ jobs:
           set -euo pipefail
           module_root="$RUNNER_TEMP/vmodules/antono2/opencl"
           install -d "$module_root"
-          install -m 0644 opencl.v convenience.v ownership.v program.v event.v \
-            image.v svm.v capabilities.v external_interop.v v.mod "$module_root/"
+          cp *.v v.mod VERSION LICENSE GENERATOR_COMMIT "$module_root/"
+          cp -R include algorithms "$module_root/"
           VMODULES="$RUNNER_TEMP/vmodules" .ci-v3/v -new-compiler -check test/main.c.v
           VMODULES="$RUNNER_TEMP/vmodules" .ci-v3/v -new-compiler -check examples/vector_add/main.v
+          VMODULES="$RUNNER_TEMP/vmodules" .ci-v3/v -new-compiler -check examples/getting_started/main.v
+          VMODULES="$RUNNER_TEMP/vmodules" .ci-v3/v -new-compiler -check examples/algorithms/main.v
           VMODULES="$RUNNER_TEMP/vmodules" .ci-v3/v -new-compiler -check abi/main.c.v
       - name: Run V3 backend smoke tests with TinyCC
         run: |
@@ -229,6 +240,10 @@ jobs:
             -cc tcc run test
           VMODULES="$RUNNER_TEMP/vmodules" .ci-v3/v -new-compiler -n \
             -cc tcc run examples/vector_add
+          VMODULES="$RUNNER_TEMP/vmodules" .ci-v3/v -new-compiler -n \
+            -cc tcc run examples/getting_started
+          VMODULES="$RUNNER_TEMP/vmodules" .ci-v3/v -new-compiler -n \
+            -cc tcc run examples/algorithms
 
   windows-abi-compile:
     runs-on: windows-2022
@@ -252,16 +267,18 @@ jobs:
         run: |
           $module = Join-Path $HOME '.vmodules/antono2/opencl'
           New-Item -ItemType Directory -Force $module | Out-Null
-          Copy-Item opencl.v, convenience.v, ownership.v, program.v, event.v, image.v, svm.v, capabilities.v, external_interop.v, v.mod, VERSION, LICENSE, GENERATOR_COMMIT -Destination $module
+          Copy-Item *.v, v.mod, VERSION, LICENSE, GENERATOR_COMMIT -Destination $module
+          Copy-Item -Recurse include, algorithms -Destination $module
           $include = Join-Path $env:VCPKG_INSTALLATION_ROOT 'installed/x64-windows/include'
           $lib = Join-Path $env:VCPKG_INSTALLATION_ROOT 'installed/x64-windows/lib'
           New-Item -ItemType Directory -Force (Join-Path $module 'include') | Out-Null
-          Copy-Item -Recurse (Join-Path $include 'CL') -Destination (Join-Path $module 'include')
+          Copy-Item -Force (Join-Path $include 'CL/*') -Destination (Join-Path $module 'include/CL')
           New-Item -ItemType Directory -Force (Join-Path $module 'lib') | Out-Null
           Copy-Item (Join-Path $lib 'OpenCL.lib') -Destination (Join-Path $module 'lib')
           $env:OPENCL_SDK = Join-Path $env:VCPKG_INSTALLATION_ROOT 'installed/x64-windows'
           v run setup.vsh --check
           v -cc msvc -o "$env:TEMP/opencl-abi-probe.exe" abi/main.c.v
+          v -cc msvc -d opencl_dynamic -o "$env:TEMP/opencl-dynamic-probe.exe" examples/getting_started
 
   linux-dependency-master:
     name: Advisory Vulkan and GLFW master
@@ -301,7 +318,8 @@ jobs:
           mkdir -p "$HOME/.vmodules/antono2/opencl" "$HOME/.vmodules/antono2/vulkan" "$HOME/.vmodules/antono2/glfw"
           cp -a .ci-modules/vulkan/. "$HOME/.vmodules/antono2/vulkan/"
           cp -a .ci-modules/glfw/. "$HOME/.vmodules/antono2/glfw/"
-          cp opencl.v convenience.v ownership.v program.v event.v image.v svm.v capabilities.v external_interop.v v.mod "$HOME/.vmodules/antono2/opencl/"
+          cp *.v v.mod VERSION LICENSE GENERATOR_COMMIT "$HOME/.vmodules/antono2/opencl/"
+          cp -R include algorithms "$HOME/.vmodules/antono2/opencl/"
           mkdir -p "$HOME/.vmodules/antono2/opencl/include/CL"
           cp include/CL/opencl.h "$HOME/.vmodules/antono2/opencl/include/CL/"
           v -cc gcc -o "$RUNNER_TEMP/vulkan-particles" examples/vulkan_particles

API_DESIGN.md

@@ -33,12 +33,18 @@ model rather than pretending to be reference-counted like OpenCL.
 7. Platform-specific external-memory and external-semaphore loaders, opaque-FD imports, ownership handoffs and owned imported semaphores. (Implemented.)
 8. Typed two-dimensional images, owned samplers and typed shared virtual memory with explicit host/device synchronization. (Implemented.)
 
-## Ecosystem boundary
-
-This package provides Khronos-registry bindings and thin, explicit resource-management
-helpers. Higher-level numerical operations, tensor APIs and cross-backend compute dispatch
-belong in the V Scientific Library's established [`vsl.vcl`](https://github.com/vlang/vsl/tree/main/vcl)
-and [`vsl.compute`](https://github.com/vlang/vsl/tree/main/compute) layers. New work in those
-areas should integrate with and be coordinated through VSL rather than creating a competing
-compute framework here. The native handles exposed by this package remain available for
-adapters and interoperability work.
+## Ecosystem scope
+
+The package includes optional, reusable device-resident algorithms alongside
+thin Khronos bindings. `algorithms` begins with unsigned scan and stable index
+compaction, accepting native-backed buffers, reusable scratch and event dependencies.
+Empty inputs, capacity, ordering and arithmetic behavior are explicit contracts.
+
+VSL integration and reuse are encouraged where APIs and ownership match. They
+are not prerequisites for delivering useful OpenCL algorithms here. Tensor APIs,
+cross-backend dispatch and application-specific simulation rules remain separate
+concerns; additions are evaluated by concrete consumers and maintenance cost.
+
+See [helper reference](docs/helpers.md), [algorithms](docs/algorithms.md), and
+[runtime and caching](docs/runtime.md) for the added session, transfer, binary
+cache and optional dynamic-loader APIs.

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- Add capability-based sessions, reusable scratch storage, owned asynchronous
+  transfers, work-group queries and binary program caches with source fallback.
+- Add optional device-resident inclusive scan and stable index compaction with
+  explicit synchronization and CPU comparison examples.
+- Add opt-in runtime loading with useful missing-runtime diagnostics while
+  retaining the default linked build.
+- Add runnable first-use examples, setup probes, parameter/lifetime tables,
+  synchronized documentation checks, and broader compiler/runtime CI coverage.
+
+
 - Prevent implicit copying of every owned OpenCL wrapper with `@[nocopy]` and
   provide explicit `clone_ref()` operations backed by the corresponding native
   retain calls. SVM allocations remain uniquely owned because OpenCL provides

DISTRIBUTION_FILES

@@ -9,10 +9,19 @@ README.md
 REGISTRY_COMMIT
 VERSION
 abi/main.c.v
+algorithms/algorithms.v
 capabilities.v
 convenience.v
 convenience_test.v
+docs/algorithms.md
+docs/convenience.md
+docs/helpers.md
+docs/runtime.md
+docs/validation.md
 event.v
+examples/algorithms/main.v
+examples/algorithms_benchmark/main.v
+examples/getting_started/main.v
 examples/image_svm/README.md
 examples/image_svm/main.v
 examples/vector_add/main.v
@@ -47,11 +56,20 @@ examples/vulkan_particles/zero_copy_smoke.v
 external_interop.v
 image.v
 include/CL/opencl.h
+include/opencl_runtime.h
 opencl.v
 ownership.v
 program.v
+program_cache.v
+runtime.v
+scratch.v
+session.v
 setup.vsh
 svm.v
+test/helpers_test.v
 test/pointer_abi_shim.c
 test/pointer_abi_test.v
+test/test_dynamic_runtime.py
+tools/check_docs.py
+transfer.v
 v.mod

GENERATOR_COMMIT

@@ -1 +1 @@
-5a5fa4656b07cb93794cb3dce47492c31f9957d6
+ff80e7d4835a56e347ec38e7a42a7821e99e622a