Skip to main content

LOGO


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

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, str
  • list[...] of allowed types
  • dict[...] of allowed types (typically dict[str, ...])
  • nested combinations of the above
  • @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.

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.
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

  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).
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

cthreads-0.1.0.tar.gz (237.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

cthreads-0.1.0-cp313-cp313-win_amd64.whl (1.6 MB view details)

Uploaded CPython 3.13Windows x86-64

cthreads-0.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.1 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

cthreads-0.1.0-cp312-cp312-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.12Windows x86-64

cthreads-0.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.6 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

cthreads-0.1.0-cp311-cp311-win_amd64.whl (943.0 kB view details)

Uploaded CPython 3.11Windows x86-64

cthreads-0.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

cthreads-0.1.0-cp310-cp310-win_amd64.whl (618.0 kB view details)

Uploaded CPython 3.10Windows x86-64

cthreads-0.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (605.1 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

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

Hashes for cthreads-0.1.0.tar.gz
Algorithm Hash digest
SHA256 f5ac77edafb0cecf1fe2d72f50b9b372a4cf7336b6e9c6c6c59b8b26fb3e7f34
MD5 e62941cfe7e4d5840e72df4b183440c5
BLAKE2b-256 0a8485466fd4ead7cd51667499c4d65cd7a6b3538f4dcfa44d0f85eb9a919d07

See more details on using hashes here.

Provenance

The following attestation bundles were made for cthreads-0.1.0.tar.gz:

Publisher: release.yml on K-T0BIAS/CThreads

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

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

Hashes for cthreads-0.1.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 240f62f13e042165c491e261d6165f76f9d90c36a1805e34fe3cd71f8b86601e
MD5 2dbc8e13fb8c21424eec4f2a1eda166f
BLAKE2b-256 08a4c52db698c9cef7482affd5aa918f0eb819c22b01512e47c17276e4ca6d78

See more details on using hashes here.

Provenance

The following attestation bundles were made for cthreads-0.1.0-cp313-cp313-win_amd64.whl:

Publisher: release.yml on K-T0BIAS/CThreads

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

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

File hashes

Hashes for cthreads-0.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c16e6f569839914469969117bb1a7c08b634e49e6b70cb8d953edfeae003e89a
MD5 ba7b47b4d36c0daaa333375f8e908f8b
BLAKE2b-256 afa75af6aef3007058b0e705eb49190263f991c5694a2cb0eacab91a62ca94e5

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

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

Hashes for cthreads-0.1.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 55a4ca6635e9a5714ac6704849aded051ab0c71472a1756f08f0e8ef148ef228
MD5 016a69fc3b64f7e8ae207fc6650b68c4
BLAKE2b-256 42ea59ed04a1480743ca6f5ad9e74a8cce20e0009ac8b8b329533717cb353b48

See more details on using hashes here.

Provenance

The following attestation bundles were made for cthreads-0.1.0-cp312-cp312-win_amd64.whl:

Publisher: release.yml on K-T0BIAS/CThreads

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

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

File hashes

Hashes for cthreads-0.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 26adce2c85d0817970b0a2f78187a0436a748700ef5e9ee5c605ca02395a8c8b
MD5 cb9d2ab7dae4687a9212ad2891e4b19d
BLAKE2b-256 e7acfe586ae76e146513cf8be95eccd7e533f0c081b58f6e0cef3bccf3c08264

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

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

Hashes for cthreads-0.1.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 ccd4d726e8cf2cac0f244619dbe68c692aa81bcaaa1bc32561e527d283803ea0
MD5 606c2e77fa1d7c60c82a91c8f3fe5919
BLAKE2b-256 57f5063c4e8895bbeada092900fd7965676a7aaa84ad5c87b56cc9d0db1543eb

See more details on using hashes here.

Provenance

The following attestation bundles were made for cthreads-0.1.0-cp311-cp311-win_amd64.whl:

Publisher: release.yml on K-T0BIAS/CThreads

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

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

File hashes

Hashes for cthreads-0.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 74c8d12806d3a94746f07068074dd35ffdcb281a791165edaa1158585f9172ee
MD5 1e6288257d885559ce581080361afcaa
BLAKE2b-256 a3fb254591c0bf383488fa0357e9b3e2f2ffdae608ae48d3700ba390b814e5c6

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

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

Hashes for cthreads-0.1.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 183ed09ccf40d16486df6ca0dd44291cef0acba8a100b21aa4fd4adcb9ffc02b
MD5 5dd40671e094e5c8d367a9a248578b24
BLAKE2b-256 fbb79c37cc66f5980efcb4c405203e785b00b2bfbd351a6e919928f8fac7c011

See more details on using hashes here.

Provenance

The following attestation bundles were made for cthreads-0.1.0-cp310-cp310-win_amd64.whl:

Publisher: release.yml on K-T0BIAS/CThreads

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

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

File hashes

Hashes for cthreads-0.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2c8fb2c94a7818cc8330a1e826bdc920dbda5b019b41be5b01b1c90ef4262c34
MD5 f1d3f6d384cba4cdf965e2075ebf3f50
BLAKE2b-256 23697f739ddb7531d97099091e208915b91ad994db72b1114abe650c52619111

See more details on using hashes here.

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

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

9 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page