An event loop for asyncio written in Rust

rsloop is a PyO3-based asyncio event loop implemented in Rust.

Each rsloop.Loop owns a dedicated Rust runtime thread for loop coordination and I/O work. That thread runs an rsloop-specialized vibeio runtime, using io_uring on Linux, IOCP on Windows, and native kqueue readiness on macOS. Plain TCP / Unix socket reads and non-TLS server accepts run on that runtime. Python callbacks, tasks, and coroutines still run on the thread that calls run_forever() or run_until_complete() (usually the main Python thread).

The package exposes:

• a native extension module at rsloop._loop
• a Python wrapper in python/rsloop/__init__.py
• rsloop.Loop, rsloop.EventLoopPolicy, rsloop.new_event_loop(), rsloop.run(...), rsloop.install(), rsloop.uninstall(), and rsloop.build_info()

Repository metadata currently targets Python >=3.10. The native runtime requires Linux 6.1+, macOS 13+, or Windows 11+ so its hot paths can rely on modern completion, timer, and scheduler primitives.

Documentation

Project documentation now lives in docs/.

If you are new to the repository, start with:

• docs/index.md
• docs/getting-started.md
• docs/how-it-works.md
• docs/project-structure.md

To browse the docs locally with MkDocs:

uvx --from mkdocs mkdocs serve

Install

From PyPI:

pip install rsloop

With uv:

uv add rsloop

From conda-forge, using pixi:

pixi add rsloop

Usage

Simple entry point:

import rsloop


async def main(): ...


rsloop.run(main())

Install as the default asyncio event loop policy:

import asyncio
import rsloop

rsloop.install()
try:
    asyncio.run(main())
finally:
    rsloop.uninstall()

Manual loop creation also works:

import asyncio
import rsloop

loop = rsloop.new_event_loop()
asyncio.set_event_loop(loop)
try:
    loop.run_until_complete(...)
finally:
    asyncio.set_event_loop(None)
    loop.close()

Importing rsloop also patches asyncio.set_event_loop() so Python 3.10 can accept an rsloop.Loop instance, matching the behavior exercised by tests/test_run.py.

Custom Async Rust Extensions

rsloop now exposes a small Rust interop API for downstream PyO3 extensions. That lets you write your own async Rust code, return it to Python as an awaitable, and run it under the active rsloop event loop.

The public entry point is rsloop::rust_async:

• get_current_locals(...)
• future_into_py(...)
• future_into_py_with_locals(...)
• local_future_into_py(...)
• local_future_into_py_with_locals(...)
• re-exports of TaskLocals and into_future_with_locals(...)

See examples/rust/README.md for a complete extension example built with maturin.

Verified Surface Area

The current codebase implements these user-facing areas.

Loop lifecycle and scheduling:

• run_forever, run_until_complete, stop, close
• time, is_running, is_closed
• get_debug, set_debug
• call_soon, call_soon_threadsafe, call_later, call_at
• returned Handle and TimerHandle objects with cancel() / cancelled()

Tasks, futures, and execution helpers:

• create_future, create_task
• set_task_factory, get_task_factory
• set_exception_handler, get_exception_handler, call_exception_handler, default_exception_handler
• set_default_executor, run_in_executor
• shutdown_asyncgens, shutdown_default_executor
• callback execution under captured contextvars.Context
• asyncio.get_running_loop() support while running on rsloop
• rsloop.run(...) helper, with asyncio.run(..., loop_factory=...) integration on Python 3.12+

I/O and networking:

• add_reader, remove_reader, add_writer, remove_writer
• sock_recv, sock_recv_into, sock_sendall, sock_accept, sock_connect
• getaddrinfo, getnameinfo
• create_server, create_connection
• create_unix_server, create_unix_connection
• connect_accepted_socket
• returned Server objects with close(), is_serving(), get_loop(), and sockets()
• returned StreamTransport objects with write(), writelines(), close(), abort(), is_closing(), write_eof(), can_write_eof(), get_extra_info(), get_protocol(), set_protocol(), pause_reading(), resume_reading(), is_reading()

Pipes, subprocesses, and signals:

• connect_read_pipe, connect_write_pipe
• subprocess_exec, subprocess_shell
• returned ProcessTransport and ProcessPipeTransport objects
• higher-level compatibility with asyncio.create_subprocess_exec() and asyncio.create_subprocess_shell()
• Unix subprocess options including cwd, env, executable, pass_fds, start_new_session, process_group, user, group, extra_groups, umask, and restore_signals
• add_signal_handler, remove_signal_handler

Profiling:

• profile(...), profiler_running(), start_profiler(), stop_profiler()
• opt-in transport counters through transport_stats() and reset_transport_stats()

Set RSLOOP_TRANSPORT_STATS=1 before importing rsloop to enable the transport counters. They report read completions and bytes, Python-thread read drains, wakeups, staged and direct writes, and Windows completion-to-poll rebinds. Counters remain disabled by default so diagnostics add only one predictable branch to transport hot paths.

Fast Streams

Importing rsloop patches asyncio.open_connection() and asyncio.start_server() by default.

That import-time behavior is controlled by RSLOOP_USE_FAST_STREAMS and can be disabled with:

export RSLOOP_USE_FAST_STREAMS=0

The native fast-stream path is used only when:

• the running loop is an rsloop.Loop
• ssl is unset or None

Otherwise rsloop falls back to the stdlib asyncio.streams helpers.

The implementation lives in src/transport/stream/fast.rs and is backed by the lower level transport code in src/transport/stream/mod.rs.

Runtime Model

The runtime is centered on one vibeio runtime per loop:

• the loop coordination thread is always the central scheduler
• plain TCP / Unix socket reads and non-TLS accept loops use vibeio on that thread across supported platforms
• Windows TCP transports, including custom asyncio.Protocol implementations, start in IOCP completion mode and rebind to readiness mode before start_tls synchronously reclaims a socket
• generic add_reader / add_writer descriptors use cancellable OS-poll workers because vibeio does not expose arbitrary raw-descriptor registration
• some transport paths still fall back to helper threads, especially TLS I/O, TLS server accept, and parts of the legacy transport write path

The runtime dependency is now unified, but the codebase has not finished eliminating every helper thread yet.

Transport overload safeguards use conservative defaults: inbound reads pause at 1 MiB of pending data per connection, buffered writes are capped at 64 MiB, and a TLS server admits at most 256 simultaneous handshakes. The last two limits can be adjusted before importing rsloop with RSLOOP_MAX_WRITE_BUFFER_BYTES and RSLOOP_MAX_PENDING_TLS_HANDSHAKES.

Current Limitations

These gaps are visible in the current implementation.

• TLS uses a rustls backend with a narrower compatibility surface than CPython's OpenSSL-backed ssl module. In particular, encrypted private keys are not supported yet, and the fast-stream monkeypatch still falls back to stdlib helpers whenever ssl is enabled. TLS transport internals also still use helper-thread paths instead of the runtime-thread vibeio socket path.
• Subprocess support still has one notable gap: preexec_fn remains unsupported because running arbitrary Python between fork() and exec() is unsafe in this runtime model.
• Unix-specific APIs remain Unix-specific: create_unix_server, create_unix_connection, add_signal_handler, remove_signal_handler.
• Platform-specific limitations still apply: Unix socket APIs and Unix signal handlers remain Unix-only, and several subprocess options such as pass_fds, user, group, and umask are still specific to Unix process spawning.
• The transport runtime model is still in transition: plain socket reads and non-TLS accepts now run on the loop runtime thread on all supported platforms, but generic descriptor watches, writes, and TLS-heavy paths are not fully collapsed onto that same single-threaded I/O path yet.

Build

Quick check:

cargo check

Release build and editable install:

cargo build --release
uv run --with maturin maturin develop --release

Build release wheels into dist/wheels:

scripts/build-wheels.sh

scripts/build-wheels.sh currently defaults to CPython 3.10 3.11 3.12 3.13 3.14 plus free-threaded 3.14t, and uses uv python install / uv python find to locate interpreters.

Profiling

Profiling is behind the Cargo feature profiler and is disabled by default. Build or install with that feature first:

cargo build --release --features profiler
uv run --with maturin maturin develop --release --features profiler

Then wrap the code you want to inspect:

import rsloop

with rsloop.profile():
    rsloop.run(main())

Or manage the session manually:

import rsloop

rsloop.start_profiler()
try:
    rsloop.run(main())
finally:
    rsloop.stop_profiler()

This starts a Tracy client inside the process. Build a release binary, open the Tracy desktop profiler, then connect to the running process while the profiled code is executing.

Release wheels do not include profiler support. Build locally with --features profiler to enable it. The Tracy feature set is aimed at local profiling: enable, only-localhost, and sampling.

For very short-lived runs you can force the process to block on exit until a server has connected and drained all data by setting TRACY_NO_EXIT=1 in the environment.

If the extension was built without --features profiler, profile() and start_profiler() raise a runtime error.

Examples

Run the repository examples from the project root:

uv run python examples/01_basics.py
uv run python examples/02_fd_and_sockets.py
uv run python examples/03_streams.py
uv run python examples/04_unix_and_accepted_socket.py
uv run python examples/05_pipes_signals_subprocesses.py

Example files: examples/01_basics.py, examples/02_fd_and_sockets.py, examples/03_streams.py, examples/04_unix_and_accepted_socket.py, examples/05_pipes_signals_subprocesses.py.

The repository also includes:

• examples/fastapi_service.py for running the same FastAPI app on stdlib asyncio, uvloop, or rsloop
• benchmarks/compare_event_loops.py for callback, task, and TCP stream comparisons

Benchmark

uv run --with maturin maturin develop --release
uv run --with uvloop python benchmarks/compare_event_loops.py

An example output from that script on macOS (arm64) with CPython 3.14:

callbacks (200,000 ops)
loop           median_s       best_s      ops_per_s     peak_rss   vs_fastest    slower_by
rsloop         0.033083     0.032710      6,045,401     67.5 MiB        1.00x         0.0%
uvloop         0.040958     0.040721      4,883,026     72.8 MiB        1.24x        23.8%
asyncio        0.082233     0.082093      2,432,114     65.3 MiB        2.49x       148.6%

tasks (50,000 ops)
loop           median_s       best_s      ops_per_s     peak_rss   vs_fastest    slower_by
rsloop         0.063593     0.063286        786,247     37.6 MiB        1.00x         0.0%
uvloop         0.069614     0.069420        718,251     38.4 MiB        1.09x         9.5%
asyncio        0.108114     0.107502        462,473     36.1 MiB        1.70x        70.0%

tcp_streams (5,000 ops)
loop           median_s       best_s      ops_per_s     peak_rss   vs_fastest    slower_by
rsloop         0.090940     0.083355         54,981     32.2 MiB        1.00x         0.0%
uvloop         0.133182     0.127404         37,543     31.5 MiB        1.46x        46.5%
asyncio        0.302337     0.299813         16,538     29.6 MiB        3.32x       232.5%

See benchmarks/README.md for workload details and extra flags, and examples/README.md for the FastAPI loop comparison example.

Acknowledgements

rsloop builds on the Python asyncio model and is implemented with PyO3 on the Rust side. Runtime and socket I/O are powered by vibeio.

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for the full text.