loopmini 0.1.1__tar.gz

loopmini-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+      - run: pip install -e '.[dev]'
+      - run: pytest -q
+
+  build:
+    needs: test
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: PyO3/maturin-action@v1
+        with:
+          args: --release --out dist -i python3.10 -i python3.11 -i python3.12 -i python3.13
+          manylinux: auto
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: -o dist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-sdist
+          path: dist
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

loopmini-0.1.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+tags
+target/
+dist/
+build/
+.venv/
+venv/
+.env
+.DS_Store
+.ipynb_checkpoints/
+Cargo.lock
+.pytest_cache/
+.sesskey

loopmini-0.1.1/Cargo.lock

@@ -0,0 +1,271 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "concurrent-queue"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "hermit-abi"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "loopmini"
+version = "0.1.1"
+dependencies = [
+ "polling",
+ "pyo3",
+ "tokio",
+]
+
+[[package]]
+name = "mio"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
+dependencies = [
+ "libc",
+ "wasi",
+ "windows-sys",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "polling"
+version = "3.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d0e4f59085d47d8241c88ead0f274e8a0cb551f3625263c05eb8dd897c34218"
+dependencies = [
+ "cfg-if",
+ "concurrent-queue",
+ "hermit-abi",
+ "pin-project-lite",
+ "rustix",
+ "windows-sys",
+]
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4688ddedf473e32662b9b067670129a8afb8c18e351482c70d62ba4a88171e8b"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f41027e41b4bd03f6e60f9f417fe24a6341a6bb744edd62b6f709f2a52ea30e9"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e591a95526fead067432c3b3a33fc74770b87b1e04e73671090d9c2055a2b327"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73225868fc1cd84eef2c3c230ddb91273bf1de46aeb8a4248da76d32a0924a1c"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "571575aa3749fa6216757dd47d2a3e7ef360f329a40f0666a9fbd14889024952"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+
+[[package]]
+name = "socket2"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "tokio"
+version = "1.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
+dependencies = [
+ "libc",
+ "mio",
+ "pin-project-lite",
+ "socket2",
+ "windows-sys",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]

loopmini-0.1.1/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "loopmini"
+version = "0.1.1"
+edition = "2021"
+license = "Apache-2.0"
+description = "Rust-backed asyncio event loop"
+repository = "https://github.com/AnswerDotAI/loopmini"
+readme = "README.md"
+
+[lib]
+name = "loopmini"
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+pyo3 = { version = ">=0.28", features = ["py-clone"] }
+polling = "3"
+tokio = { version = "1", features = ["rt", "time", "net"] }
+
+[dev-dependencies]
+tokio = { version = "1", features = ["rt-multi-thread"] }
+
+[features]
+extension-module = ["pyo3/extension-module"]

loopmini-0.1.1/DEV.md

@@ -0,0 +1,204 @@
+# Developer guide
+
+## Why this exists
+
+Kernmini's Rust engine (see kernmini `meta/ROUGH.md`, "Separate project idea: a
+Tokio-backed asyncio loop" and the 2026-08-28 review) needs Python kernels to
+run arbitrary user asyncio code. loopmini tests whether a Rust reactor can host
+that loop with full asyncio compatibility. The compatibility bar is the full
+public asyncio surface, because solveit users run arbitrary packages; the
+strategy for meeting it is maximal reuse of CPython's own asyncio machinery,
+with Rust owning only what Python cannot express well.
+
+## Crate/Python split
+
+A key goal is that Rust crates and PyO3 wrappers share code: the same reactor
+must be drivable by a pure-Rust kernel (as kernmini's native crate will be).
+So the crate has three layers:
+
+- `src/reactor.rs`: `Reactor<H>`, a PyO3-free, Tokio-free core generic over
+  the handle type. Ready queue, timer map, fd interest map (oneshot `polling`
+  sources, re-armed on delivery), thread-safe `schedule_ts` + notify, and the
+  turn phases: `next_timeout` / `poll` / `process` / `take_batch` /
+  `requeue_front`. `poll` holds no locks, so a driver may block in it with the
+  GIL released. The crate builds as an rlib, so a Rust consumer instantiates
+  `Reactor<RustHandle>` directly.
+- `src/tokio_core.rs`: the reactor hosted on a Tokio current-thread runtime.
+  Tokio waits on the kqueue's own fd (a kqueue is pollable) and a zero-timeout
+  drain then collects events, so the kqueue-native level/oneshot semantics
+  that asyncio's `add_reader` contract needs survive Tokio's edge-triggered
+  driver. Rust futures spawned on the runtime advance during every blocking
+  poll, with the GIL released: the shared-reactor path for kernmini's engine.
+  Zero-timeout turns skip the runtime entirely, because entering it rounds the
+  wait up to the timer driver's ~1ms tick.
+- `src/pyreactor.rs`: `PyReactor`, the Python-facing pyclass: the scheduling
+  and readiness methods plus the canonical dispatch loop (`check_signals` each
+  turn, `py.detach` around `poll`, EINTR retry, and the injected-exception
+  requeue rule, which must exist exactly once). `loopmini._core` registers it
+  on an owned runtime; kernmini's Python feature compiles the same struct and constructs
+  it with `PyReactor::with_handle` on kernmini's runtime. Rust has no stable
+  dylib ABI, so runtimes and reactors never cross extension boundaries: each
+  extension compiles the crate in, and the Python-visible reactor methods are
+  the only shared surface. `Loop(reactor=...)` accepts such a foreign reactor.
+- `src/lib.rs`: module registration and the public re-exports (`ReactorCore`,
+  `TokioCore`, `PyReactor`) for embedding crates.
+
+Python (`python/loopmini/loop.py`) implements `asyncio.AbstractEventLoop` by
+delegating scheduling to the reactor and reusing stock `Handle`, `TimerHandle`,
+`Task`, `Future`, and `wrap_future`. That reuse is a design decision, not a
+shortcut: it buys exact contextvars, cancellation, and introspection semantics
+and removes the most version-sensitive surface. `run_forever` on the main
+thread routes signals through `signal.set_wakeup_fd` into an fd the reactor
+watches, matching `BaseSelectorEventLoop`.
+
+## Implemented surface
+
+Beyond the scheduling core: TCP transports (`transports.py`: `SockTransport`
+speaking both `Protocol` and `BufferedProtocol`, with `TCP_NODELAY` set as the
+standard loop does, and `MiniServer` with the accept loop),
+`create_connection`/`create_server` and their Unix-socket twins,
+`connect_accepted_socket`, UDP via `DatagramTransport` and
+`create_datagram_endpoint`, `start_tls` (including the gh-142352
+buffered-StreamReader move), TLS client and server via stock `asyncio.sslproto`
+over our transports, `getaddrinfo`/`getnameinfo` through the executor, and
+`add_signal_handler`/`remove_signal_handler` dispatched from the
+`set_wakeup_fd` socketpair (main-thread loops only, as in the standard loop),
+pipe transports (`connect_read_pipe`/`connect_write_pipe`), and
+`subprocess_exec`/`subprocess_shell` (`subproc.py`: Popen spawned in the
+executor since fork/exec blocks, one reaper thread per child as in asyncio's
+default ThreadedChildWatcher, and pipe transports over the child's fds).
+
+Contracts learned from the oracles, kept working by them: `remove_reader`
+cancels the stored `Handle`, so an already-queued readiness callback for a
+removed fd never fires (anyio's futures assume it); `connection_lost` is
+scheduled exactly once however `close()`, `abort()`, and fatal errors overlap
+(anyio's `aclose` does close-then-abort, and a missed schedule leaks the
+socket); a cancelled connect attempt closes its socket; and a raised
+`create_connection` error must not keep a referrer to the attempt-error list.
+`MiniServer` mirrors 3.13 `Server` exactly (test_server pins it):
+`wait_closed()` returns only once the server is closed *and* the last client
+transport is gone, `close_clients()`/`abort_clients()` act on a `WeakSet` of
+attached transports, a cancelled `serve_forever` closes the server and its
+clients before re-raising, and a Unix socket path is unlinked at close only
+when its inode still matches the one bound (`cleanup_socket=False` disables).
+A cancelled timer leaves the reactor's timer map at once: `schedule_at`
+returns a `(deadline µs, seq)` key, the `TimerHandle` subclass carries it, and
+`_timer_handle_cancelled` removes the entry. Retention until the original
+deadline would grow memory for an hour per cancelled `wait_for(..., 3600)`.
+From the aiohttp suite: `loop.time()` must be anchored to `time.monotonic`
+(connectors compare the two directly), so the reactor clock carries a
+constant offset captured at loop creation; and a transport must not hold an
+explicit `memoryview` export of its write buffer across a `send` that can
+raise, because the raised exception's traceback keeps the export alive and
+the buffer can then never be resized (send the bytearray itself, as the
+standard loop does).
+
+## Deliberately not implemented yet
+
+Sendfile and Windows.
+`AbstractEventLoop` raises `NotImplementedError` for these, which is the
+honest signal while the compatibility ladder is climbed. Next rungs and their
+oracles (anyio/aiohttp/httpx/websockets test suites) are listed in kernmini
+`meta/ROUGH.md`.
+
+## Tests
+
+The tiers, so the inner loop stays seconds:
+
+- `pytest -q` per change (~2s).
+- `pytest -m oracle -n auto` when a feature lands, not per edit.
+- `pytest -m bench -s` and `pytest -m soak -s` only when performance or
+  stability is the question.
+- `chkstyle` once, at the final PR stage, never per edit.
+
+`pytest -q`. Ten integration stories, deliberately few: scheduling/tasks/
+threads (timers, contextvars, gather, TaskGroup, timeout, cancellation,
+cross-thread wakeup, to_thread), socket I/O through the reactor (accept/
+connect/backpressure on a 5MB payload), asyncio streams echo with drain
+backpressure, a background task surviving between `run_until_complete` calls
+(the kernel-persistence story), KeyboardInterrupt injection with the loop
+reused afterwards, uvicorn serving an ASGI app fetched by urllib and by
+httpx-over-anyio, TLS echo against a throwaway openssl cert, a subprocess
+round-trip (exec and shell, streams and communicate), and the
+interrupt-torture story: window-scoped `PyThreadState_SetAsyncExc` injection
+under stream/timer/cross-thread load, mirroring kernmini's
+`sync_execution_context` contract (0.5s by default; `LOOPMINI_TORTURE_SECONDS`
+extends it), and the KI-at-`_run`-entry orphan repro that pins the
+traceback-depth requeue rule. Rust-side unit tests should exist only for
+reactor invariants Python stories cannot reach.
+
+Two CPython 3.13 facts the torture test depends on, discovered the hard way:
+an async-injected exception raised at an eval-breaker check escapes the
+raising frame even past a same-frame `try/except` (open regression
+[gh-139622](https://github.com/python/cpython/issues/139622); 3.12 and 3.14
+unaffected), so the guard must sit in a parent frame; and a busy window
+shorter than the GIL switch interval (5ms) is invisible to a sampling thread,
+because the GIL is only ever released while the window is closed.
+
+## The compatibility oracles
+
+Four external suites are the conformance measure, run in-repo through
+`tests/test_oracle.py` (marked `oracle`, deselected by default):
+
+```bash
+pytest -m oracle -n auto          # all four suites, one worker per module
+pytest -m oracle -k uvloop        # one suite; add "and test_tcp" etc. for one module
+```
+
+`tests/oracle_util.py` fetches and caches what each suite needs under
+`~/.cache/loopmini-oracle` (override with `LOOPMINI_ORACLE_CACHE`):
+
+- CPython's own test_asyncio (uvloop's strategy). This uv-managed Python ships
+  without the stdlib `test` package, so the matching source tarball is fetched
+  and its functional modules run under a loopmini event-loop policy. Suites
+  asserting standard-loop internals (base_events, selector_events,
+  unix_events) are not fair oracles and are excluded.
+- anyio's test suite, via its sanctioned alternative-loop mechanism: the sdist
+  matching the installed version is unpacked and a loopmini entry added to
+  `asyncio_params` in its conftest. Runs as a subprocess; requires the anyio
+  test deps (`trustme`, `blockbuster`) in the venv. blockbuster's
+  blocking-call detector allowlists Popen's blocking os.read only under
+  `asyncio/base_events.py`, which is one reason the Popen spawn goes through
+  the executor.
+- uvloop's test suite, from a source clone (`LOOPMINI_UVLOOP_REPO`, default
+  `~/aai-ws/links/uvloop`): its loop-parameterized test classes are cloned
+  onto loopmini with `implementation='asyncio'`, so branchy tests take the
+  standard-loop expectation paths. `test_tcp` needs pyOpenSSL and is skipped
+  without it.
+- aiohttp's test suite: the sdist is unpacked, uvloop is stubbed to loopmini in
+  its conftest so `--aiohttp-loop=uvloop` selects it, and its blockbuster
+  fixture gains an allowlist entry for `MiniServer.close` (the same
+  unlink-if-unchanged stat asyncio's `_stop_serving` is allowlisted for).
+  Runs the pure-Python aiohttp (`AIOHTTP_NO_EXTENSIONS=1`), with a private
+  `--basetemp` because its permission tests leave chmod-000 dirs that
+  pytest's numbered-dir sweeper cannot remove, fatal under aiohttp's
+  `filterwarnings = error`. Deselected, with reasons in `test_oracle.py`:
+  tests that fail identically on the standard loop in this venv, and one
+  test that mock-patches `loop.time()`, which only steers loops whose timer
+  arithmetic reads Python-level time each turn (real uvloop fails it too).
+
+Status on 2026-08-28: all green; 25 oracle tests, the first three suites in
+~17s under xdist and aiohttp's ~4,200 tests in a further ~2 minutes.
+
+## The soak gate
+
+`pytest -m soak -s` runs a kernel-shaped workload on one loopmini loop for
+`LOOPMINI_SOAK_SECONDS` (default 30): a fasthtml app on uvicorn under
+threaded httpx load, a websocket echo server with a bot-style client, a
+housekeeping tick, and periodic cells submitted from another thread, as a
+kernel would. It asserts zero errors, bounded fd growth, and that every
+component made progress. It watches stability, not speed.
+
+## Benchmarks
+
+`pytest -m bench -s` prints loopmini vs the standard loop on loop-bound
+microbenchmarks; informational, never gating. Numbers on 2026-08-28 (M-series
+macOS): call_soon 1.10x, sleep0 1.12x, tcp_echo 1.10x, task spawn 2.48x
+(stdlib=1.0). The spawn gap is per-task PyO3 boundary crossings (two to three
+`schedule` calls per task lifecycle at ~0.5µs each); loop startup is at parity.
+Closing it would need handles represented Rust-side, which is later-rung work.
+
+## Style and releases
+
+fastai style (`chkstyle` before committing). Releases via fastship; the tree
+carries the next version.