greenlet

greenlet is a C extension that provides lightweight, in-process coroutines for CPython, spun off from Stackless Python’s tasklet model. Instead of relying on the operating system or an event loop to schedule execution, greenlets are explicit micro-threads that you switch between yourself, giving precise control over when control flow moves from one unit of work to another.

Because it exposes no implicit scheduler, greenlet acts as a foundational building block rather than a full concurrency framework: higher-level libraries like gevent and eventlet use it to implement cooperative networking, and SQLAlchemy’s async extension uses it to bridge sync and async code paths.

What You Get

• A greenlet class representing an independent, switchable execution context with its own call stack
• Explicit switch() semantics for transferring control and passing values between greenlets
• Support for nested generator-like control flow without Python’s native yield keyword
• Tracing hooks (gettrace/settrace) for observing greenlet switches
• contextvars integration so context state follows greenlet switches correctly
• Prebuilt wheels covering CPython on Linux, macOS, and Windows across multiple architectures

Common Use Cases

• Powering gevent’s and eventlet’s cooperative, socket-level concurrency models
• Bridging synchronous and asynchronous code paths, as SQLAlchemy’s asyncio extension does internally
• Implementing custom cooperative schedulers or actor-style micro-threads on top of a low-level primitive
• Building generator-like constructs that can yield from nested function calls

Under The Hood

Architecture: greenlet’s core is a small state machine around per-greenlet C stacks. src/greenlet/greenlet.cpp and the TGreenlet*/TMainGreenlet/TUserGreenlet files implement stack allocation, saving/restoring, and the actual switch() transfer of control via platform-specific assembly in slp_platformselect.h and the platform/ directory; PyGreenlet.cpp wraps this machinery as the Python-visible greenlet type. There is no scheduler anywhere in the codebase — every switch is caller-initiated, which is what lets libraries like gevent build their own event loops on top without fighting an existing one.

Tech Stack: Implemented as a CPython C/C++ extension (about 52% C++, 12% C) with a thin Python layer (src/greenlet/__init__.py) re-exporting the compiled _greenlet module’s symbols. Built via setuptools/pyproject.toml, with per-platform assembly stubs to handle stack switching correctly across x86, x86-64, ARM, and other architectures, plus manylinux/macOS/Windows wheel builds in CI.

Code Quality: The src/greenlet/tests/ directory contains over 5,300 lines of tests, including dedicated fail_*.py scripts that exercise crash and error-recovery paths (e.g. fail_switch_three_greenlets.py, fail_cpp_exception.py), plus test_contextvars.py, test_gc.py, and test_interpreter_shutdown.py covering edge cases like garbage collection interaction and interpreter teardown — reflecting the project’s long history of hardening against subtle stack-corruption bugs.

API Design: The public surface is deliberately minimal — greenlet(fn), .switch(*args), getcurrent(), and a couple of tracing hooks — which keeps the primitive easy to wrap but means correct usage (avoiding orphaned greenlets, understanding exception propagation across switches) requires reading the docs rather than guessing from the API shape alone.