talyn 0.5.0

Talyn: A robust, stable, and realistically fast Zig-powered event loop for Python's asyncio.

Talyn: Robust, Stable AsyncIO Event Loop for Python

Talyn is a robust, exceptionally stable, and realistically fast asyncio event loop drop-in replacement for Python, powered by the asynchronous capabilities of Zig and io_uring.

Talyn prioritizes correctness, complete system safety, and high usability over artificial micro-benchmark superiority. It is fully compatible with CPython's standard single-threaded and free-threaded (GIL-disabled) runtimes.

---

🚀 Features

• Realistic Speed: Designed to deliver solid and reliable I/O performance on Linux by leveraging io_uring's native kernel-side asynchronous completion queues.
• Robust & Crash-Resistant: Meticulously hardened against circular reference memory leaks, stack alignment faults, signal interrupt deadlocks, and use-after-free bugs.
• Full Asyncio Compatibility: Passes 100% of standard Python asyncio, subprocess, transports, and connection-lifecycle test suites.
• Modern Packaging: Fully migrated to PEP 517/518 standard declarative pyproject.toml configuration.
• GIL-Disabled Free-Threading Ready: Fully compatible with python3.13t and python3.14t without memory races.

---

📜 Requirements

• Python: >= 3.13 (Tested and verified under CPython 3.13, 3.14, 3.13t (free-threaded), and 3.14t (free-threaded))
• Linux Kernel: >= 7.0 (Verified on Linux Kernel 7.0.x)
• Zig Compiler (for source builds): 0.16.0 (Fedora packages)

[!NOTE] Tested Platform Verification: Talyn has been built, compiled, and verified extensively under Fedora 43-44 on an x86_64 architecture equipped with an Intel(R) Core(TM) Ultra 7 265 processor. Compatibility with other Linux distributions, older kernels, or alternative hardware architectures (e.g. AArch64) has not been verified yet. We welcome feedback and pull requests for other environments!

---

🔧 Installation

To compile and install Talyn locally, run:

pip install -e .

⚡ Optimization & Target Compilation (For Developers & Power Users)

By default, the pre-built wheels generated by build.sh are compiled targeting a generic x86_64 CPU architecture baseline to ensure 100% universal compatibility across all 64-bit modern x86 Linux processors (e.g., matching standard PyPI manylinux wheel compatibility).

If you are compiling from source, you can customize the compilation optimize mode and target CPU architecture to unleash maximum performance:

1. Compile and Optimize for your Native CPU (Highly Recommended)

To compile Talyn so that it takes full advantage of your host's exact CPU instructions (such as AVX2, AVX-512, cache alignment, etc.):

# Omit TALYN_CPU so Zig defaults to native CPU optimization
TALYN_OPTIMIZE=ReleaseSafe pip install .

2. Configure Compilation Modes

You can control Zig's optimize mode by setting the TALYN_OPTIMIZE environment variable (defaults to Debug for developer convenience):

• TALYN_OPTIMIZE=Debug (Default): Compiles with heavy runtime assertions and debug symbols.
• TALYN_OPTIMIZE=ReleaseSafe: Compiles with full optimizations but keeps safety checks (e.g. out-of-bounds, overflows). Highly recommended for production.
• TALYN_OPTIMIZE=ReleaseFast: Compiles with maximum optimizations, disabling safety checks for peak execution speed.

3. Target a Specific CPU microarchitecture

You can force Zig to compile for a specific target CPU microarchitecture (like x86_64_v2 or x86_64_v3):

TALYN_OPTIMIZE=ReleaseSafe TALYN_CPU=x86_64_v3 pip install .

---

📦 Basic Usage

import talyn
import asyncio

async def main():
    print("Hello from Talyn!")
    await asyncio.sleep(1)
    print("Goodbye from Talyn!")

# Run using Talyn event loop
talyn.run(main())

---

💝 Historical Credits & Origin

Talyn is spun off from Leviathan, an event loop originally pioneered by Enrique Mora. Enrique Mora's creative spark and vision of merging Zig, io_uring, and asyncio laid the critical foundation and architecture of this project.

As Talyn evolved, the implementation underwent a complete systems-level refactoring to transition from a theoretical prototype to a production-grade, crash-resistant runtime:

• Eliminated multi-crossing Zig/Python vectorcall overhead by implementing a native C step trampoline.
• Redesigned completion handlers into flat, GC-safe ring buffers.
• Fully audited and resolved all memory-leak reference cycles under concurrent connections.

To honor the project's roots and Enrique's early work:

• The original Leviathan README can be viewed at: docs/historical/leviathan-readme.md
• The original preliminary benchmarks can be viewed at: docs/historical/leviathan-benchmark.md

---

📖 Project Story

• Development Journey — The full story: from discovery to challenges, the shift from "ultra-fast" to "realistic fast and stable", and how Talyn was built.
• Why Talyn? — The personal story and meaning behind the new name.

---

📄 License

This project is licensed under the MIT License. See LICENSE.md for details.