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
- Guides
- Release (GitHub / PyPI)
- Math & linalg
- Compiler notes
- Sync / state writeback
- API reference
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.
From PyPI
Published wheels (Linux / Windows x86_64) and the sdist are on PyPI:
pip install cthreads
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)
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.
Introduction
Annotate what should become a native kernel:
@Thread- functions / methods compiled to C++@Threadable- classes compiled to C++ structs (shared state across kernels)
Supported types
Allowed in annotations (arguments, returns, locals, Threadable fields):
int,float,bool,strlist[...]of allowed typesdict[...]of allowed types (typicallydict[str, ...])- nested combinations of the above
@Threadableclasses- 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.
from cthreads import Thread
@Thread
def my_example_function() -> None:
return None
Rules
- Typed parameters and a return type (use
-> Nonewhen there is no value). - No
*args/**kwargs. - Locals must be annotated with an allowed type (
x: int = 0). - Inside the body, only call other
@Threadfunctions/methods, pluspython math (import math),cthreads.modules, not arbitrary Python. - Return values must match the declared return type.
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.
from cthreads import Threadable
@Threadable
class MyExample:
x: float
y: float
Rules
- All fields are typed at class scope (dataclass-style annotations).
- Do not define / override
__init__. The decorator injects a dataclass-style constructor (ExampleClass(1, "x")orExampleClass(attr1=1); omitted fields zero / empty, matching C++T{}). - Kernel methods must use
@Threadand takeselflike normal methods. - Method argument / return annotations must be allowed types (or
-> None).
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
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.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cthreads-0.1.0.tar.gz.
File metadata
- Download URL: cthreads-0.1.0.tar.gz
- Upload date:
- Size: 237.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f5ac77edafb0cecf1fe2d72f50b9b372a4cf7336b6e9c6c6c59b8b26fb3e7f34
|
|
| MD5 |
e62941cfe7e4d5840e72df4b183440c5
|
|
| BLAKE2b-256 |
0a8485466fd4ead7cd51667499c4d65cd7a6b3538f4dcfa44d0f85eb9a919d07
|
Provenance
The following attestation bundles were made for cthreads-0.1.0.tar.gz:
Publisher:
release.yml on K-T0BIAS/CThreads
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cthreads-0.1.0.tar.gz -
Subject digest:
f5ac77edafb0cecf1fe2d72f50b9b372a4cf7336b6e9c6c6c59b8b26fb3e7f34 - Sigstore transparency entry: 2667616309
- Sigstore integration time:
-
Permalink:
K-T0BIAS/CThreads@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/K-T0BIAS
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Trigger Event:
release
-
Statement type:
File details
Details for the file cthreads-0.1.0-cp313-cp313-win_amd64.whl.
File metadata
- Download URL: cthreads-0.1.0-cp313-cp313-win_amd64.whl
- Upload date:
- Size: 1.6 MB
- Tags: CPython 3.13, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
240f62f13e042165c491e261d6165f76f9d90c36a1805e34fe3cd71f8b86601e
|
|
| MD5 |
2dbc8e13fb8c21424eec4f2a1eda166f
|
|
| BLAKE2b-256 |
08a4c52db698c9cef7482affd5aa918f0eb819c22b01512e47c17276e4ca6d78
|
Provenance
The following attestation bundles were made for cthreads-0.1.0-cp313-cp313-win_amd64.whl:
Publisher:
release.yml on K-T0BIAS/CThreads
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cthreads-0.1.0-cp313-cp313-win_amd64.whl -
Subject digest:
240f62f13e042165c491e261d6165f76f9d90c36a1805e34fe3cd71f8b86601e - Sigstore transparency entry: 2667616482
- Sigstore integration time:
-
Permalink:
K-T0BIAS/CThreads@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/K-T0BIAS
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Trigger Event:
release
-
Statement type:
File details
Details for the file cthreads-0.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: cthreads-0.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
- Upload date:
- Size: 2.1 MB
- Tags: CPython 3.13, manylinux: glibc 2.27+ x86-64, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c16e6f569839914469969117bb1a7c08b634e49e6b70cb8d953edfeae003e89a
|
|
| MD5 |
ba7b47b4d36c0daaa333375f8e908f8b
|
|
| BLAKE2b-256 |
afa75af6aef3007058b0e705eb49190263f991c5694a2cb0eacab91a62ca94e5
|
Provenance
The following attestation bundles were made for cthreads-0.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:
Publisher:
release.yml on K-T0BIAS/CThreads
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cthreads-0.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl -
Subject digest:
c16e6f569839914469969117bb1a7c08b634e49e6b70cb8d953edfeae003e89a - Sigstore transparency entry: 2667616431
- Sigstore integration time:
-
Permalink:
K-T0BIAS/CThreads@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/K-T0BIAS
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Trigger Event:
release
-
Statement type:
File details
Details for the file cthreads-0.1.0-cp312-cp312-win_amd64.whl.
File metadata
- Download URL: cthreads-0.1.0-cp312-cp312-win_amd64.whl
- Upload date:
- Size: 1.3 MB
- Tags: CPython 3.12, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
55a4ca6635e9a5714ac6704849aded051ab0c71472a1756f08f0e8ef148ef228
|
|
| MD5 |
016a69fc3b64f7e8ae207fc6650b68c4
|
|
| BLAKE2b-256 |
42ea59ed04a1480743ca6f5ad9e74a8cce20e0009ac8b8b329533717cb353b48
|
Provenance
The following attestation bundles were made for cthreads-0.1.0-cp312-cp312-win_amd64.whl:
Publisher:
release.yml on K-T0BIAS/CThreads
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cthreads-0.1.0-cp312-cp312-win_amd64.whl -
Subject digest:
55a4ca6635e9a5714ac6704849aded051ab0c71472a1756f08f0e8ef148ef228 - Sigstore transparency entry: 2667616406
- Sigstore integration time:
-
Permalink:
K-T0BIAS/CThreads@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/K-T0BIAS
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Trigger Event:
release
-
Statement type:
File details
Details for the file cthreads-0.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: cthreads-0.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
- Upload date:
- Size: 1.6 MB
- Tags: CPython 3.12, manylinux: glibc 2.27+ x86-64, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
26adce2c85d0817970b0a2f78187a0436a748700ef5e9ee5c605ca02395a8c8b
|
|
| MD5 |
cb9d2ab7dae4687a9212ad2891e4b19d
|
|
| BLAKE2b-256 |
e7acfe586ae76e146513cf8be95eccd7e533f0c081b58f6e0cef3bccf3c08264
|
Provenance
The following attestation bundles were made for cthreads-0.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:
Publisher:
release.yml on K-T0BIAS/CThreads
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cthreads-0.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl -
Subject digest:
26adce2c85d0817970b0a2f78187a0436a748700ef5e9ee5c605ca02395a8c8b - Sigstore transparency entry: 2667616513
- Sigstore integration time:
-
Permalink:
K-T0BIAS/CThreads@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/K-T0BIAS
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Trigger Event:
release
-
Statement type:
File details
Details for the file cthreads-0.1.0-cp311-cp311-win_amd64.whl.
File metadata
- Download URL: cthreads-0.1.0-cp311-cp311-win_amd64.whl
- Upload date:
- Size: 943.0 kB
- Tags: CPython 3.11, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ccd4d726e8cf2cac0f244619dbe68c692aa81bcaaa1bc32561e527d283803ea0
|
|
| MD5 |
606c2e77fa1d7c60c82a91c8f3fe5919
|
|
| BLAKE2b-256 |
57f5063c4e8895bbeada092900fd7965676a7aaa84ad5c87b56cc9d0db1543eb
|
Provenance
The following attestation bundles were made for cthreads-0.1.0-cp311-cp311-win_amd64.whl:
Publisher:
release.yml on K-T0BIAS/CThreads
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cthreads-0.1.0-cp311-cp311-win_amd64.whl -
Subject digest:
ccd4d726e8cf2cac0f244619dbe68c692aa81bcaaa1bc32561e527d283803ea0 - Sigstore transparency entry: 2667616364
- Sigstore integration time:
-
Permalink:
K-T0BIAS/CThreads@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/K-T0BIAS
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Trigger Event:
release
-
Statement type:
File details
Details for the file cthreads-0.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: cthreads-0.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
- Upload date:
- Size: 1.1 MB
- Tags: CPython 3.11, manylinux: glibc 2.27+ x86-64, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
74c8d12806d3a94746f07068074dd35ffdcb281a791165edaa1158585f9172ee
|
|
| MD5 |
1e6288257d885559ce581080361afcaa
|
|
| BLAKE2b-256 |
a3fb254591c0bf383488fa0357e9b3e2f2ffdae608ae48d3700ba390b814e5c6
|
Provenance
The following attestation bundles were made for cthreads-0.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:
Publisher:
release.yml on K-T0BIAS/CThreads
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cthreads-0.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl -
Subject digest:
74c8d12806d3a94746f07068074dd35ffdcb281a791165edaa1158585f9172ee - Sigstore transparency entry: 2667616389
- Sigstore integration time:
-
Permalink:
K-T0BIAS/CThreads@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/K-T0BIAS
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Trigger Event:
release
-
Statement type:
File details
Details for the file cthreads-0.1.0-cp310-cp310-win_amd64.whl.
File metadata
- Download URL: cthreads-0.1.0-cp310-cp310-win_amd64.whl
- Upload date:
- Size: 618.0 kB
- Tags: CPython 3.10, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
183ed09ccf40d16486df6ca0dd44291cef0acba8a100b21aa4fd4adcb9ffc02b
|
|
| MD5 |
5dd40671e094e5c8d367a9a248578b24
|
|
| BLAKE2b-256 |
fbb79c37cc66f5980efcb4c405203e785b00b2bfbd351a6e919928f8fac7c011
|
Provenance
The following attestation bundles were made for cthreads-0.1.0-cp310-cp310-win_amd64.whl:
Publisher:
release.yml on K-T0BIAS/CThreads
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cthreads-0.1.0-cp310-cp310-win_amd64.whl -
Subject digest:
183ed09ccf40d16486df6ca0dd44291cef0acba8a100b21aa4fd4adcb9ffc02b - Sigstore transparency entry: 2667616464
- Sigstore integration time:
-
Permalink:
K-T0BIAS/CThreads@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/K-T0BIAS
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Trigger Event:
release
-
Statement type:
File details
Details for the file cthreads-0.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: cthreads-0.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
- Upload date:
- Size: 605.1 kB
- Tags: CPython 3.10, manylinux: glibc 2.27+ x86-64, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2c8fb2c94a7818cc8330a1e826bdc920dbda5b019b41be5b01b1c90ef4262c34
|
|
| MD5 |
f1d3f6d384cba4cdf965e2075ebf3f50
|
|
| BLAKE2b-256 |
23697f739ddb7531d97099091e208915b91ad994db72b1114abe650c52619111
|
Provenance
The following attestation bundles were made for cthreads-0.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:
Publisher:
release.yml on K-T0BIAS/CThreads
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cthreads-0.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl -
Subject digest:
2c8fb2c94a7818cc8330a1e826bdc920dbda5b019b41be5b01b1c90ef4262c34 - Sigstore transparency entry: 2667616339
- Sigstore integration time:
-
Permalink:
K-T0BIAS/CThreads@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/K-T0BIAS
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@65ee752f46e139811dd3f9c20adc70bf61b7a4be -
Trigger Event:
release
-
Statement type: