24 gpu 04 gpu gpu public path launch pool emit entry

.gitignore

@@ -52,6 +52,7 @@ api/
 # >>> cthreads (auto)
 __Thread__/
 __Threadable__/
+__Gpu__/
 .cthreads_cache.json
 cthreads_kernels.dll
 cthreads_kernels.so

LICENSE

@@ -0,0 +1,127 @@
+MIT License
+
+Copyright (c) 2026 Tobias Karusseit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================================
+Third-party notices
+================================================================================
+
+cthreads depends on (or may optionally link / redistribute) the following
+third-party components. Their licenses apply to those components only.
+Full license texts are available from the upstream projects.
+
+--------------------------------------------------------------------------------
+pybind11
+--------------------------------------------------------------------------------
+Used to bind the native `_ext` module to Python (FetchContent or system
+package via CMake).
+
+License: BSD-3-Clause
+Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>, All rights reserved.
+Homepage: https://github.com/pybind/pybind11
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+--------------------------------------------------------------------------------
+Vulkan (Khronos Group) — optional, CTHREADS_GPU=ON
+--------------------------------------------------------------------------------
+GPU builds use Vulkan headers from the Vulkan SDK / CMake Vulkan package.
+At runtime, cthreads loads the system Vulkan loader (for example vulkan-1)
+dynamically; the loader and ICD are provided by the platform / GPU vendor
+and are not redistributed as part of cthreads by default.
+
+Vulkan-Headers / related Khronos materials are typically licensed under the
+Apache License, Version 2.0.
+Homepage: https://github.com/KhronosGroup/Vulkan-Headers
+License reference: https://www.apache.org/licenses/LICENSE-2.0
+
+--------------------------------------------------------------------------------
+Khronos glslang — GPU GLSL -> SPIR-V (CTHREADS_GPU=ON)
+--------------------------------------------------------------------------------
+When built with CTHREADS_GPU=ON, cthreads FetchContent-vendors and statically
+links Khronos glslang into `_ext` to implement `_ext.gpu.compile_glsl`.
+This is the same compiler engine Google shaderc wraps. End users of a GPU
+wheel do not need glslc or the Vulkan SDK shader tools.
+
+License: Apache License, Version 2.0 (with BSD-style components in the tree)
+Homepage: https://github.com/KhronosGroup/glslang
+License reference: https://www.apache.org/licenses/LICENSE-2.0
+
+Upstream license text is copied at build time into:
+
+    cthreads/gpu/third_party_notices/
+
+(see README.md there). Redistribute that directory with any binary that
+includes the GPU extension.
+
+--------------------------------------------------------------------------------
+scikit-build-core
+--------------------------------------------------------------------------------
+Used as the Python build backend to drive CMake (build-time dependency; not
+part of the runtime import of cthreads).
+
+License: Apache License, Version 2.0
+Homepage: https://github.com/scikit-build/scikit-build-core
+License reference: https://www.apache.org/licenses/LICENSE-2.0
+
+--------------------------------------------------------------------------------
+Apache License, Version 2.0 (summary for Apache-licensed deps above)
+--------------------------------------------------------------------------------
+You may reproduce and distribute copies of Apache-2.0 works under the terms
+of that license. A copy of the full license text is available at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the Apache License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the Apache License for the specific language governing permissions and
+limitations under the License.
+
+--------------------------------------------------------------------------------
+Python
+--------------------------------------------------------------------------------
+cthreads is designed to run on CPython. The Python interpreter and standard
+library are governed by the Python Software Foundation License.
+Homepage: https://www.python.org/

docs/STYLE.md

@@ -77,7 +77,9 @@ def example_fn() -> None:
 
 1. the use of special utf characters is not permitted
 ```latex
-Exmaple:
+Example:
 — should be - or depending on ctx ,. etc.
 → should be ->
 ```
+
+2. `from __future__ import annotations` is only permitted iff its used to avoid import errors, improve import performance, with typechecking, or to avoid any other error. Otherwise explicit imports are preffered to ensure easy dependency maintenace

docs/internals/gpu/context.md

@@ -23,15 +23,16 @@ The `Context` struct holds all of that state for the whole process. There is one
 
 ### `void init()`
 
-Opens the loader, creates instance and device, resolves entry points, marks `ready = true`, and creates the TransferEngine (command pool and fence). Throws typed-style error strings (for example `cthreads.gpu.VulkanLoaderNotFound`) that Python maps into exceptions in `cthreads.gpu`.
+Opens the loader, creates instance and device, resolves entry points, marks `ready = true`, and creates the TransferEngine and LaunchEngine. Throws typed-style error strings (for example `cthreads.gpu.VulkanLoaderNotFound`) that Python maps into exceptions in `cthreads.gpu`.
 
 Call this when you need the GPU. Python `cthreads.gpu.init()` ends up here.
 
 ### `void shutdown()`
 
 Destroys children first, then parents:
 
-1. TransferEngine (staging buffer, fence, command pool)
+1. LaunchEngine (free fences, then command pool)
+2. TransferEngine (staging buffer, fence, command pool)
 2. Shader cache entries (pipelines and layouts)
 3. Logical device
 4. Instance
@@ -99,6 +100,10 @@ Used by [module / launch](./module.md): `vkCmdBindPipeline`, `vkCmdBindDescripto
 
 See the next section. `transfer_engine_mutex` serializes use of the single shared engine.
 
+### LaunchEngine and mutex
+
+`LaunchEngine` owns the process-lifetime command pool used by `launch_gpu_kernel`. Jobs checkout a command buffer + fence, submit under `launch_engine_mutex`, wait their own fence on join, then return the CB/fence to free lists. Overlapping jobs are supported; one shared fence is not.
+
 ## Technical terms
 
 - Vulkan loader: system library that discovers Installable Client Drivers (ICDs), which are the vendor GPU drivers.
@@ -144,6 +149,7 @@ A future pool of engines is discussed for CPU threads launching GPU work. See [g
 6. `vkCreateDevice` opens the logical device; `vkGetDeviceQueue` gets the queue.
 7. Resolve device-level functions (buffers, commands, shaders, descriptors).
 8. Create TransferEngine pool and fence.
+9. Create LaunchEngine command pool (CB/fence free lists grow on demand).
 9. Set `ready = true`.
 
 ## Key Vulkan calls during shutdown (story order)

docs/internals/gpu/module.md

@@ -13,13 +13,15 @@ Depends on: [Context](./context.md), [Pack](./pack.md), [Descriptors](./descript
 
 `launch_gpu_kernel` is the GPU analogue of CPU `spawn_from_meta`: build a `GpuPack`, wire descriptors, record bind+dispatch, submit with a fence, and return a job handle. `SpawnedGpuKernel::join` waits on that fence, downloads ref lists into the same Python objects, then releases Vulkan state. There is no OS worker thread and no mid-run `sync_state`.
 
-Public `gpu()` / `@Gpu` (later) will call these same types. Tests exercise them today via `_ext.gpu.testing.smoke_launch_saxpy`.
+Public `gpu()` / `@Gpu` (later) will call these same types. Product pybind:
+`_ext.gpu.launch_gpu_kernel` + `_ext.gpu.GpuJob`. Tests register smoke SPIR-V
+via `_ext.gpu.testing.register_smoke_saxpy`, then launch on the product path.
 
 ## Technical terms
 
 - Fence: CPU waits until the submitted dispatch has finished.
 - Writeback: copy device list SSBOs back into the kept Python `list` objects (`pass_as` ref).
-- Per-job command pool: short-lived pool that owns the launch command buffer (not the TransferEngine pool).
+- Per-job command buffer + fence: checked out from Context `LaunchEngine` for the job lifetime; returned on join (supports overlapping launches). The command **pool** is process-lifetime on Context.
 
 ## Struct `SpawnedGpuKernel`
 
@@ -49,4 +51,6 @@ Value scalars are not written back. Threadable/schema marshal is later.
 
 ## Testing
 
-`smoke_launch_saxpy` registers committed saxpy SPIR-V, launches, joins, and asserts `y` matches CPU saxpy. Pytest: `tests/unit/test_gpu_shader.py::test_live_smoke_launch_saxpy`.
+`register_smoke_saxpy` puts committed saxpy SPIR-V in ShaderCache (test-only).
+Pytest drives product `launch_gpu_kernel` + `GpuJob.join` and asserts `y`:
+`tests/unit/test_gpu_shader.py::test_live_launch_saxpy_product_path`.

docs/internals/gpu/pack.md

@@ -97,4 +97,7 @@ destroy_gpu_pack
 
 ## Testing today
 
-`_ext.gpu.testing` exposes pack round-trip helpers (float and int packs) and `smoke_launch_saxpy` (full launch + join writeback). Pytest: `tests/unit/test_gpu_pack.py`, `tests/unit/test_gpu_shader.py`.
+`_ext.gpu.testing` exposes pack round-trip helpers (float and int packs) and
+`register_smoke_saxpy` (SPIR-V cache only). Launch/join use product
+`_ext.gpu.launch_gpu_kernel`. Pytest: `tests/unit/test_gpu_pack.py`,
+`tests/unit/test_gpu_shader.py`.

docs/internals/gpu/shader.md

@@ -25,7 +25,8 @@ Per-launch objects (GpuPack buffers, descriptor sets, fences) are not stored her
 
 ## Access rights
 
-- Writers (registry / testing, via `add` once friended): insert new entries.
+- Writers: `ShaderRegistry::register_spirv` only (friend of `ShaderCache`; also
+  exposed as `_ext.gpu.register_shader`). Tests use the same writer.
 - Everyone else: `get` returns a const reference.
 - Context shutdown: `clear` destroys all Vulkan objects, then empties the map.
 

docs/vk_guide/05-dynamic-loading.md

@@ -81,4 +81,4 @@ When adding a new Vulkan call in `memory.cpp`, first check: is its `PFN_` on `Co
 | `VulkanNoDevice` | No compute-capable GPU |
 | `VulkanInitFailed: vkCreate… failed` | Driver rejected create |
 
-Python maps these string prefixes to exception types in `cthreads.gpu.errors`.
+Python maps these string prefixes to exception types in `cthreads.gpu.frontend.errors`.

docs/vk_guide/13-map-to-our-code.md

@@ -46,8 +46,8 @@ Newcomer-oriented C++ module docs: [docs/internals/gpu/README.md](../internals/g
 
 1. Read guide 09-12.
 2. Open `pack.hpp` / `descriptors.hpp` / `shader_cache.hpp` / `module.hpp`.
-3. Trace `smoke_launch_saxpy` in `gpu/testing/shader_smoke.cpp` end-to-end.
-4. Run `tests/unit/test_gpu_shader.py::test_live_smoke_launch_saxpy`.
+3. Trace product `launch_gpu_kernel` after `testing.register_smoke_saxpy`.
+4. Run `tests/unit/test_gpu_shader.py::test_live_launch_saxpy_product_path`.
 
 ## Build flag reminder
 

pyproject.toml

@@ -11,10 +11,12 @@ name = "cthreads"
 version = "0.1.1"
 description = "Compile @Threadable / @Thread Python into native C++ kernels and run them off the GIL."
 requires-python = ">=3.10"
+license = { file = "LICENSE" }
 keywords = ["threading", "multithreading", "codegen", "python compiler", "cpp", "pybind11"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
     "Programming Language :: C++",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
@@ -53,6 +55,7 @@ wheel.exclude = [
     "**/*.pyc",
 ]
 sdist.include = [
+    "LICENSE",
     "src/cthreads/cpp/**",
     "src/cthreads/python/cthreads/**",
     "src/cthreads/python/api/**",

src/cthreads/cpp/CMakeLists.txt

@@ -145,24 +145,85 @@ endif()
 if(CTHREADS_GPU)
     find_package(Vulkan REQUIRED) # vulkan sdk for headers/includes
     message(STATUS "cthreads GPU: ON (Vulkan)")
+
+    # Vendor Khronos glslang (GLSL -> SPIR-V). Same compiler engine shaderc uses.
+    # Linked statically into _ext so end users need no glslc / extra SDK tools.
+    include(FetchContent)
+    set(ENABLE_GLSLANG_BINARIES OFF CACHE BOOL "" FORCE)
+    set(ENABLE_HLSL OFF CACHE BOOL "" FORCE)
+    set(ENABLE_OPT OFF CACHE BOOL "" FORCE)
+    set(ENABLE_SPVREMAPPER OFF CACHE BOOL "" FORCE)
+    set(ENABLE_CTEST OFF CACHE BOOL "" FORCE)
+    set(SKIP_GLSLANG_INSTALL ON CACHE BOOL "" FORCE)
+    set(BUILD_EXTERNAL OFF CACHE BOOL "" FORCE)
+    set(GLSLANG_TESTS OFF CACHE BOOL "" FORCE)
+    set(ENABLE_GLSLANG_JS OFF CACHE BOOL "" FORCE)
+    FetchContent_Declare(
+        glslang
+        GIT_REPOSITORY https://github.com/KhronosGroup/glslang.git
+        GIT_TAG        15.1.0
+        GIT_SHALLOW    TRUE
+    )
+    FetchContent_MakeAvailable(glslang)
+    message(STATUS "cthreads GPU: vendored glslang for compile_glsl")
+
     target_sources(_ext PRIVATE
-    "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/context.cpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/memory.cpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/pack.cpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/shader_cache.cpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/shader.cpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/descriptors.cpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/module.cpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/gpu/testing/pack_roundtrip.cpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/gpu/testing/shader_smoke.cpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/bindings/gpu_module.cpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/bindings/gpu_testing_module.cpp"
-        # GPU: context, memory, GpuPack, shader cache/entry (+ test-only roundtrip)
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/context.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/memory.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/pack.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/shader_cache.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/state.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/shader.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/descriptors.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/module.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/impl/compile_glsl.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/testing/pack_roundtrip.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/testing/shader_smoke.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/bindings/gpu_module.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/bindings/gpu_testing_module.cpp"
     )
     target_include_directories(_ext PRIVATE
         ${CMAKE_CURRENT_SOURCE_DIR}/gpu/headers
         ${CMAKE_CURRENT_SOURCE_DIR}/gpu
         ${Vulkan_INCLUDE_DIRS}
     )
     target_compile_definitions(_ext PRIVATE CTHREADS_WITH_GPU=1)
-endif()
+    target_link_libraries(_ext PRIVATE
+        glslang
+        SPIRV
+        glslang-default-resource-limits
+    )
+
+    # Ship upstream license texts next to the Python package (Apache/BSD notices).
+    set(_cthreads_gpu_notices_out
+        "${_cthreads_py_out}/gpu/third_party_notices")
+    set(_cthreads_gpu_notices_src
+        "${CMAKE_CURRENT_SOURCE_DIR}/gpu/third_party_notices")
+    file(MAKE_DIRECTORY "${_cthreads_gpu_notices_out}")
+    if(EXISTS "${_cthreads_gpu_notices_src}/README.md")
+        configure_file(
+            "${_cthreads_gpu_notices_src}/README.md"
+            "${_cthreads_gpu_notices_out}/README.md"
+            COPYONLY
+        )
+    endif()
+    if(DEFINED glslang_SOURCE_DIR)
+        foreach(_lic IN ITEMS LICENSE.txt LICENSE.TXT LICENSE)
+            if(EXISTS "${glslang_SOURCE_DIR}/${_lic}")
+                configure_file(
+                    "${glslang_SOURCE_DIR}/${_lic}"
+                    "${_cthreads_gpu_notices_out}/glslang-${_lic}"
+                    COPYONLY
+                )
+                break()
+            endif()
+        endforeach()
+    endif()
+
+    if(DEFINED SKBUILD AND NOT (DEFINED SKBUILD_STATE AND SKBUILD_STATE STREQUAL "editable"))
+        install(DIRECTORY "${_cthreads_gpu_notices_out}/"
+            DESTINATION cthreads/gpu/third_party_notices
+            OPTIONAL
+        )
+    endif()
+endif()