Metadata-Version: 2.1
Name: cthreads-gpu
Version: 0.2.0
Summary: cthreads with Vulkan GPU (@Gpu) support built into _ext. Install via pip install cthreads-gpu (do not install alongside cthreads).
Keywords: threading,multithreading,codegen,python compiler,cpp,pybind11
License: 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/
         
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Project-URL: Homepage, https://github.com/K-T0BIAS/CThreads
Project-URL: Repository, https://github.com/K-T0BIAS/CThreads
Project-URL: Issues, https://github.com/K-T0BIAS/CThreads/issues
Project-URL: Documentation, https://github.com/K-T0BIAS/CThreads/tree/main/docs
Requires-Python: >=3.10
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: scikit-build-core>=0.10; extra == "dev"
Description-Content-Type: text/markdown


![LOGO](./docs/__ressources/CTHREADS_03_1.svg)

----

**cthreads** compiles a typed Python subset into C++ so work can run on real OS threads **without the GIL** allowing true concurrency without `multiprocessing`'s process boundaries and pickling tax.

Use `@Thread` on functions/methods and `@Threadable` on classes. The whitelist covers the usual scalars and containers, plus your own Threadable types. Code runs at native speed while you keep a Python-shaped control flow (jobs, pools, sync).

----

### Docs

- [Install](./docs/install.md) (includes GPU / Vulkan notes)
- [Guides](./docs/index.md)
- [GPU guides (0.2.0)](./docs/guide/gpu/README.md)
- [Release (GitHub / PyPI)](./docs/release.md)
- [Math & linalg](./docs/guide/math_and_linalg.md)
- [Compiler notes](./docs/COMPILER.md)
- [Sync / state writeback](./docs/sync_state_docs.md)
- [API reference](./docs/API.md)

----

# Install

**Python >= 3.10**, a **C++17** compiler, and **CMake >= 3.18** (CMake is only needed to build the native `_ext` module). Full toolchain notes: [docs/install.md](./docs/install.md).

### From PyPI

Published wheels (Linux / Windows x86_64) and the sdist are on [PyPI](https://pypi.org/project/cthreads/):

```bash
pip install cthreads
# Vulkan GPU (@Gpu) support (full package; do not install alongside cthreads):
pip install cthreads-gpu
```

You still need a C++ compiler for the first `thread(...)` (user kernels). On Linux, wheels include a prebuilt `_ext`; CMake is only required if you install from the sdist or develop from source.

### From this repo (editable)

```bash
python -m venv .venv
# activate, then:
pip install cmake ninja    # CMake/Ninja in the venv; compiler is still system/MSVC
pip install -e ".[test]"   # or: pip install -e .
```

First `cthreads.thread(...)` auto-runs cache-checked `prepare` + `load_kernels`. Call `unload_kernels()` before a force rebuild (`thread(..., force=True)` or `prepare(force=True)`).

How we publish: [docs/release.md](./docs/release.md).

----

# Introduction

Annotate what should become a native kernel:

- **`@Thread`** - functions / methods compiled to C++
- **`@Threadable`** - classes compiled to C++ structs (shared state across kernels)
- **`@Gpu`** - functions compiled to Vulkan compute (lists of scalars; see [GPU guides](./docs/guide/gpu/README.md))

## Supported types

Allowed in annotations (arguments, returns, locals, Threadable fields):

* `int`, `float`, `bool`, `str`
* `list[...]` of allowed types
* `dict[...]` of allowed types (typically `dict[str, ...]`)
* nested combinations of the above
* [`@Threadable`](#threadable) classes
* any internal types imported by `cthreads`

This is a **whitelist**, not full Python. No arbitrary objects, no untyped values in kernels.

## `@Thread`

Marks a function or method for compilation. Pass it to `cthreads.thread(...)` to run off the GIL.

```python
from cthreads import Thread

@Thread
def my_example_function() -> None:
    return None
```

### Rules

1. **Typed parameters and a return type** (use `-> None` when there is no value).
2. **No `*args` / `**kwargs`.**
3. **Locals must be annotated** with an allowed type (`x: int = 0`).
4. Inside the body, only call other **`@Thread`** functions/methods, plus **`python math (import math)`**, **`cthreads.modules`**, not arbitrary Python.
5. Return values must match the declared return type.

```python
from cthreads import Thread

@Thread
def example_function(val1: int, val2: list[float], val3: ExampleClass) -> ExampleClass:
    var4: str = "hello there"
    var5: int = 42

    val3.some_string_attr = var4
    val3.some_int_attr = var5
    return val3
```

## `@Threadable`

Python's open object model does not map cleanly to C++. `@Threadable` marks a class so the compiler can emit a fixed C++ struct and marshal it safely.

```python
from cthreads import Threadable

@Threadable
class MyExample:
    x: float
    y: float
```

### Rules

1. **All fields are typed** at class scope (dataclass-style annotations).
2. **Do not define / override `__init__`.** The decorator injects a dataclass-style constructor (`ExampleClass(1, "x")` or `ExampleClass(attr1=1)`; omitted fields zero / empty, matching C++ `T{}`).
3. **Kernel methods must use `@Thread`** and take **`self`** like normal methods.
4. Method argument / return annotations must be allowed types (or `-> None`).

```python
from cthreads import Threadable, Thread

@Threadable
class ExampleClass:
    attr1: int
    attr2: str
    attr3: list[float]

    @Thread
    def method1(self) -> None:
        self.attr1 += 1

    @Thread
    def method2(self, string: str) -> str:
        return self.attr2 + string


obj = ExampleClass(0, "1", [2.0, 3.0])

obj.method1()
print(obj.attr1, obj.method2(" 1"))  # 1  1 1
```

**Why Threadables?**

- shared state for worker threads
- typed containers / domain objects
- grouping related kernel methods

----

# Run a `@Thread`

```python
import cthreads
from cthreads import Thread

@Thread
def example_function(lhs: float, rhs: float, count: int) -> float:
    for i in range(count):
        lhs += rhs
    return lhs

# Sync: Job -> join -> result
job = cthreads.thread(example_function, 1.5, 2.0, 200)
job.join() # starts if needed; blocks this thread (GIL released in C++)
result = job.result()

# Async: await auto-starts and returns the result (event loop stays free)
job = cthreads.thread(example_function, 1.5, 2.0, 200)
result = await job
```

Signature: `cthreads.thread(fn, *args, force: bool = False, **kwargs) -> Job`.

----

# GPU (`@Gpu`, from 0.2.0)

Vulkan compute kernels use the same "annotate then launch" idea on a separate backend:

```python
from cthreads.gpu import Gpu, GlobalIdx, gpu

@Gpu
def saxpy(n: int, a: float, x: list[float], y: list[float]) -> None:
    i: int = GlobalIdx.x
    if i >= n:
        return
    y[i] = a * x[i] + y[i]

x = [1.0, 2.0, 3.0, 4.0]
y = [10.0, 20.0, 30.0, 40.0]
gpu(saxpy, len(x), 2.0, x, y).join()
```

Full guides (concepts, best practices, examples): [docs/guide/gpu/README.md](./docs/guide/gpu/README.md).
Install / drivers: [docs/install.md](./docs/install.md#gpu-vulkan-compute).

----
