zloop 0.0.0__tar.gz

zloop-0.0.0/.gitignore

@@ -0,0 +1,17 @@
+.zig-cache/
+zig-out/
+build_err.txt
+*.so
+dist/
+build/
+__pycache__/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.venv/
+.uvicorn-upstream/
+.uvloop-upstream/
+site/
+CODEX_REVIEW.md
+DOCS_REVIEW.md

zloop-0.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Marcelo Trylesinski
+
+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.

zloop-0.0.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: zloop
+Version: 0.0.0
+Summary: An asyncio event loop with a Zig core.
+Author-email: Marcelo Trylesinski <marcelotryle@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Zig
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# zloop
+
+> [!WARNING]
+> zloop is experimental. The API and behaviour may change at any time, and it is not yet ready for production use.
+
+A drop-in [asyncio](https://docs.python.org/3/library/asyncio.html) event loop
+whose engine is written in [Zig](https://ziglang.org). It's to asyncio what
+[uvloop](https://github.com/MagicStack/uvloop) is - a real
+`asyncio.AbstractEventLoop` - except the engine is a hand-written kqueue/epoll
+reactor in Zig rather than libuv wrapped in Cython.
+
+```python
+import asyncio
+import zloop
+
+print(asyncio.run(asyncio.sleep(0, "hello from a Zig loop"), loop_factory=zloop.new_event_loop))
+```
+
+With [uvicorn](https://www.uvicorn.org):
+
+```bash
+uvicorn app:app --loop zloop:new_event_loop
+```
+
+## Why
+
+- **Drop-in.** A genuine `AbstractEventLoop`, so the asyncio ecosystem -
+  uvicorn, FastAPI, AnyIO, HTTPX - runs on it unchanged.
+- **Correct.** Passes [uvicorn](https://github.com/encode/uvicorn)'s **entire**
+  test suite (1048 tests), identical to stock asyncio, plus its own suite at
+  **100%** coverage.
+- **Fast.** Faster than uvloop on the workloads measured so far - scheduling,
+  timers, and small/medium-message socket throughput (e.g. `call_soon` +46%,
+  1 KiB echo +16% on CPython 3.14 / macOS arm64). `create_future` ties, because
+  all three loops reuse CPython's C-accelerated `_asyncio.Future`.
+
+## Benchmarks
+
+The fairest comparison is uvloop's *own* echo benchmark, run unchanged except
+for a `--zloop` server flag mirroring `--uvloop` (the client is byte-for-byte
+uvloop's). Requests/sec, higher is better - macOS arm64, CPython 3.14, 3
+workers, best of 3:
+
+| Message | Server mode | asyncio | uvloop | zloop | zloop vs uvloop |
+| --- | --- | ---: | ---: | ---: | ---: |
+| 1 KiB | proto | 113k | 113k | **121k** | **+7%** |
+| 1 KiB | buffered | 115k | 115k | **123k** | **+7%** |
+| 1 KiB | streams | 83k | 90k | **103k** | **+14%** |
+| 10 KiB | proto | 105k | 110k | **113k** | **+3%** |
+| 10 KiB | buffered | 105k | 105k | **124k** | **+18%** |
+| 10 KiB | streams | 81k | 86k | **95k** | **+11%** |
+
+For the 1-10 KiB messages common in HTTP, WebSocket frames, and RPC, zloop leads
+uvloop in every cell. The 100 KiB row is omitted: at that size the test measures
+loopback bandwidth, not the loop, and all three swing wildly run-to-run.
+
+Reproduce it with `scripts/bench` (or `bash bench_uvloop/run_matrix.sh` for the
+full matrix); the **Benchmark** CI workflow runs it on Linux and posts the table
+to the run summary.
+
+## How it works
+
+The loop *engine* lives in Zig; CPython is reused only where reimplementing
+would be reckless: driving coroutines (`asyncio.Future` / `asyncio.Task`) and
+the TLS state machine (`asyncio.sslproto`). That's exactly uvloop's boundary.
+
+```
+zloop/            Python edge - new_event_loop() factory, connection setup
+src/python/*.zig  CPython C-API adapter - Loop, Handle, Transport
+src/core/*.zig    pure-Zig domain - run-once engine, kqueue/epoll reactor, timer heap
+```

zloop-0.0.0/README.md

@@ -0,0 +1,71 @@
+# zloop
+
+> [!WARNING]
+> zloop is experimental. The API and behaviour may change at any time, and it is not yet ready for production use.
+
+A drop-in [asyncio](https://docs.python.org/3/library/asyncio.html) event loop
+whose engine is written in [Zig](https://ziglang.org). It's to asyncio what
+[uvloop](https://github.com/MagicStack/uvloop) is - a real
+`asyncio.AbstractEventLoop` - except the engine is a hand-written kqueue/epoll
+reactor in Zig rather than libuv wrapped in Cython.
+
+```python
+import asyncio
+import zloop
+
+print(asyncio.run(asyncio.sleep(0, "hello from a Zig loop"), loop_factory=zloop.new_event_loop))
+```
+
+With [uvicorn](https://www.uvicorn.org):
+
+```bash
+uvicorn app:app --loop zloop:new_event_loop
+```
+
+## Why
+
+- **Drop-in.** A genuine `AbstractEventLoop`, so the asyncio ecosystem -
+  uvicorn, FastAPI, AnyIO, HTTPX - runs on it unchanged.
+- **Correct.** Passes [uvicorn](https://github.com/encode/uvicorn)'s **entire**
+  test suite (1048 tests), identical to stock asyncio, plus its own suite at
+  **100%** coverage.
+- **Fast.** Faster than uvloop on the workloads measured so far - scheduling,
+  timers, and small/medium-message socket throughput (e.g. `call_soon` +46%,
+  1 KiB echo +16% on CPython 3.14 / macOS arm64). `create_future` ties, because
+  all three loops reuse CPython's C-accelerated `_asyncio.Future`.
+
+## Benchmarks
+
+The fairest comparison is uvloop's *own* echo benchmark, run unchanged except
+for a `--zloop` server flag mirroring `--uvloop` (the client is byte-for-byte
+uvloop's). Requests/sec, higher is better - macOS arm64, CPython 3.14, 3
+workers, best of 3:
+
+| Message | Server mode | asyncio | uvloop | zloop | zloop vs uvloop |
+| --- | --- | ---: | ---: | ---: | ---: |
+| 1 KiB | proto | 113k | 113k | **121k** | **+7%** |
+| 1 KiB | buffered | 115k | 115k | **123k** | **+7%** |
+| 1 KiB | streams | 83k | 90k | **103k** | **+14%** |
+| 10 KiB | proto | 105k | 110k | **113k** | **+3%** |
+| 10 KiB | buffered | 105k | 105k | **124k** | **+18%** |
+| 10 KiB | streams | 81k | 86k | **95k** | **+11%** |
+
+For the 1-10 KiB messages common in HTTP, WebSocket frames, and RPC, zloop leads
+uvloop in every cell. The 100 KiB row is omitted: at that size the test measures
+loopback bandwidth, not the loop, and all three swing wildly run-to-run.
+
+Reproduce it with `scripts/bench` (or `bash bench_uvloop/run_matrix.sh` for the
+full matrix); the **Benchmark** CI workflow runs it on Linux and posts the table
+to the run summary.
+
+## How it works
+
+The loop *engine* lives in Zig; CPython is reused only where reimplementing
+would be reckless: driving coroutines (`asyncio.Future` / `asyncio.Task`) and
+the TLS state machine (`asyncio.sslproto`). That's exactly uvloop's boundary.
+
+```
+zloop/            Python edge - new_event_loop() factory, connection setup
+src/python/*.zig  CPython C-API adapter - Loop, Handle, Transport
+src/core/*.zig    pure-Zig domain - run-once engine, kqueue/epoll reactor, timer heap
+```

zloop-0.0.0/build.zig

@@ -0,0 +1,65 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    // Pure-Zig unit tests for the core data structures. Defined first so
+    // `zig build test` works without any Python configuration.
+    const core_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/core/root.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        }),
+    });
+    const run_core_tests = b.addRunArtifact(core_tests);
+    const test_step = b.step("test", "Run pure-Zig core unit tests");
+    test_step.dependOn(&run_core_tests.step);
+
+    // Python build configuration is discovered by build_ext.sh and passed in as
+    // -D options or environment variables. Resolved lazily so the test step
+    // above never requires a Python toolchain.
+    const py_include = b.option([]const u8, "python-include", "Path to the CPython include dir") orelse
+        (b.graph.environ_map.get("ZLOOP_PYTHON_INCLUDE") orelse return);
+    const ext_suffix = b.option([]const u8, "ext-suffix", "Extension module suffix") orelse
+        (b.graph.environ_map.get("ZLOOP_EXT_SUFFIX") orelse return);
+
+    const core_mod = b.createModule(.{
+        .root_source_file = b.path("src/core/root.zig"),
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+    });
+
+    const mod = b.createModule(.{
+        .root_source_file = b.path("src/python/module.zig"),
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+    });
+    mod.addIncludePath(.{ .cwd_relative = py_include });
+    mod.addImport("core", core_mod);
+    // Provide atomic helpers the free-threaded headers declare but Zig's
+    // translate-c can't inline; harmless (unreferenced) on non-free-threaded builds.
+    mod.addCSourceFile(.{ .file = b.path("src/python/ft_atomics.c") });
+
+    const lib = b.addLibrary(.{
+        .name = "_zloop",
+        .root_module = mod,
+        .linkage = .dynamic,
+    });
+
+    // CPython extensions resolve interpreter symbols at load time. On macOS this
+    // requires undefined symbols to be allowed; on Linux they are global.
+    if (target.result.os.tag == .macos) {
+        lib.linker_allow_shlib_undefined = true;
+    }
+
+    // Install the shared object into the python package directory under the name
+    // CPython expects so it imports as `zloop._zloop`.
+    const out_name = b.fmt("_zloop{s}", .{ext_suffix});
+    const install = b.addInstallFileWithDir(lib.getEmittedBin(), .{ .custom = "../zloop" }, out_name);
+    b.getInstallStep().dependOn(&install.step);
+}

zloop-0.0.0/build_ext.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Build the zloop Zig extension against the interpreter that will import it.
+# Usage: ./build_ext.sh [path-to-python]   (defaults to the uvicorn venv python)
+set -euo pipefail
+
+PY="${1:-/Users/marcelotryle/dev/encode/zloop/.uvicorn-upstream/.venv/bin/python}"
+cd "$(dirname "$0")"
+
+read -r INCLUDE SUFFIX < <("$PY" -c \
+  'import sysconfig as s; print(s.get_path("platinclude"), s.get_config_var("EXT_SUFFIX"))')
+
+export ZLOOP_PYTHON_INCLUDE="$INCLUDE"
+export ZLOOP_EXT_SUFFIX="$SUFFIX"
+
+MODE="${ZLOOP_BUILD_MODE:-ReleaseFast}"
+zig build "-Doptimize=$MODE" "$@" 2>/dev/null || zig build "-Doptimize=$MODE"
+echo "built zloop/_zloop$SUFFIX against $("$PY" --version) ($INCLUDE)"

zloop-0.0.0/hatch_build.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import sysconfig
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+ROOT = Path(__file__).parent
+
+# cibuildwheel builds every macOS wheel on the arm64 runner and asks for a
+# specific arch through ARCHFLAGS; translate it into a Zig cross-compile target
+# so the produced `.so` matches the wheel tag delocate enforces.
+_MACOS_ZIG_ARCH = {"arm64": "aarch64-macos", "x86_64": "x86_64-macos"}
+
+# Pin the binary's minimum macOS to match MACOSX_DEPLOYMENT_TARGET (set by
+# cibuildwheel), so the wheel tag and the `.so`'s required OS version agree and
+# delocate accepts the repaired wheel.
+_MACOS_DEFAULT_MIN = "11.0"
+
+
+def _zig_target_args() -> list[str]:
+    archflags = os.environ.get("ARCHFLAGS", "")
+    arches = archflags.split()[1::2]  # "-arch x86_64 -arch arm64" -> ["x86_64", "arm64"]
+    if len(arches) != 1 or sys.platform != "darwin":
+        return []
+    arch = _MACOS_ZIG_ARCH.get(arches[0])
+    if not arch:
+        return []
+    min_version = os.environ.get("MACOSX_DEPLOYMENT_TARGET", _MACOS_DEFAULT_MIN)
+    return [f"-Dtarget={arch}.{min_version}"]
+
+
+def _zig_command() -> list[str]:
+    """Resolve how to invoke Zig: a `zig` on PATH, else the `ziglang` pip package.
+
+    The pip fallback (`python -m ziglang`) works identically on the host and inside
+    cibuildwheel's manylinux containers, where a host-installed `zig` isn't visible.
+    """
+    if shutil.which("zig"):
+        return ["zig"]
+    try:
+        import ziglang  # noqa: F401
+    except ImportError:
+        raise RuntimeError(
+            "Zig toolchain not found: install Zig and put it on PATH, or `pip install ziglang`."
+        ) from None
+    return [sys.executable, "-m", "ziglang"]
+
+
+class ZigBuildHook(BuildHookInterface):
+    """Compile the Zig extension against the building interpreter during the wheel build.
+
+    This makes `uv build` / `pip wheel` / cibuildwheel produce a correct, platform-tagged
+    wheel with no out-of-band step: the `.so` is built here, against `sys.executable`, and
+    `build.zig` installs it into the `zloop/` package as `_zloop<EXT_SUFFIX>`.
+    """
+
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if self.target_name != "wheel":
+            return
+
+        include = sysconfig.get_path("platinclude")
+        ext_suffix = sysconfig.get_config_var("EXT_SUFFIX")
+        if not include or not ext_suffix:
+            raise RuntimeError("could not resolve platinclude / EXT_SUFFIX from the building interpreter")
+
+        mode = os.environ.get("ZLOOP_BUILD_MODE", "ReleaseFast")
+        env = {**os.environ, "ZLOOP_PYTHON_INCLUDE": include, "ZLOOP_EXT_SUFFIX": ext_suffix}
+        subprocess.run(
+            [*_zig_command(), "build", f"-Doptimize={mode}", *_zig_target_args()],
+            cwd=ROOT,
+            env=env,
+            check=True,
+        )
+
+        artifact = f"zloop/_zloop{ext_suffix}"
+        if not (ROOT / artifact).exists():
+            raise RuntimeError(f"zig build did not produce {artifact}")
+
+        # Tag the wheel for this interpreter + platform rather than py3-none-any.
+        build_data["pure_python"] = False
+        build_data["infer_tag"] = True
+        build_data["artifacts"].append(artifact)
+
+    def clean(self, versions: list[str]) -> None:
+        for path in ROOT.glob("zloop/_zloop*.so"):
+            path.unlink()
+        for path in ROOT.glob("zloop/_zloop*.pyd"):
+            path.unlink()
+        print(f"removed compiled extensions; building Zig core via {sys.executable}", file=sys.stderr)

zloop-0.0.0/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.8.0", "ziglang==0.16.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zloop"
+description = "An asyncio event loop with a Zig core."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Marcelo Trylesinski", email = "marcelotryle@gmail.com" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Zig",
+]
+dynamic = ["version"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "coverage>=7.0",
+    "ruff",
+    "mypy",
+    "trustme",
+]
+docs = [
+    "zensical",
+    "matplotlib",  # docs/gen_bench_chart.py renders the benchmark chart
+]
+bench = [
+    "uvloop",  # the comparison baseline for bench_uvloop/bench_ci.py
+]
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+metadata = false  # drop the +<hash> local segment; PyPI rejects it on uploads
+fallback-version = "0.0.0"
+
+[tool.hatch.build.targets.wheel]
+packages = ["zloop"]
+artifacts = ["zloop/*.so"]
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.sdist]
+# Ship the sources needed to compile the extension from an sdist.
+include = ["zloop", "src", "build.zig", "build_ext.sh", "hatch_build.py"]
+
+[tool.cibuildwheel]
+# Zig comes from the `ziglang` build requirement (build isolation), so no
+# system toolchain install is needed. Skip 32-bit, musl, and PyPy: the Zig core
+# targets glibc/macOS and CPython only.
+build = "cp312-* cp313-* cp314-*"
+skip = "*-win* *_i686 *-musllinux_*"
+build-frontend = "build[uv]"
+test-command = 'python -c "import asyncio, zloop; assert asyncio.run(asyncio.sleep(0, 1), loop_factory=zloop.new_event_loop) == 1"'
+
+[tool.cibuildwheel.linux]
+# manylinux container has no Zig; the ziglang wheel in the isolated build env
+# provides it. Nothing extra to install. Each runner builds its native arch
+# (x86_64 on ubuntu-latest, aarch64 on ubuntu-24.04-arm) - running the foreign
+# manylinux container without QEMU hangs on `exec format error`.
+archs = ["auto"]
+
+[tool.cibuildwheel.macos]
+archs = ["arm64", "x86_64"]
+# Pin the wheel tag's minimum macOS; hatch_build.py passes the same version to
+# Zig so the compiled `.so` and the tag agree and delocate accepts the wheel.
+environment = { MACOSX_DEPLOYMENT_TARGET = "11.0" }
+
+[tool.pytest.ini_options]
+addopts = "-rxXs --strict-config --strict-markers"
+asyncio_mode = "auto"
+xfail_strict = true
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source_pkgs = ["zloop"]
+branch = true
+parallel = true
+omit = ["zloop/_zloop*"]
+
+[tool.coverage.report]
+precision = 2
+fail_under = 100
+show_missing = true
+skip_covered = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@overload",
+]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "FA", "UP", "RUF100"]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.mypy]
+strict = true
+warn_unused_ignores = true
+show_error_codes = true
+files = ["zloop"]
+
+[[tool.mypy.overrides]]
+# The connection-setup layer deliberately widens the asyncio loop method
+# signatures (Any / **_) the same way uvloop's stubs do; those intentional
+# overrides and Any-returns aren't real type errors.
+module = "zloop._io"
+disable_error_code = ["override", "no-any-return"]

zloop-0.0.0/src/core/clock.zig

@@ -0,0 +1,25 @@
+//! Monotonic clock. asyncio's loop.time() is time.monotonic(); we read the same
+//! CLOCK_MONOTONIC source so deadlines computed on the Python side and the Zig
+//! side agree.
+
+const std = @import("std");
+const sys = @import("sys.zig");
+
+/// Current monotonic time in nanoseconds.
+pub fn nowNs() u64 {
+    return sys.monotonicNs();
+}
+
+/// Current monotonic time in seconds as f64, matching time.monotonic().
+pub fn nowSeconds() f64 {
+    return @as(f64, @floatFromInt(nowNs())) / std.time.ns_per_s;
+}
+
+const testing = std.testing;
+
+test "clock is monotonic non-decreasing" {
+    const a = nowNs();
+    const b = nowNs();
+    try testing.expect(b >= a);
+    try testing.expect(nowSeconds() > 0);
+}