{"id":35136850,"url":"https://github.com/ankitkpandey1/uringcore","last_synced_at":"2026-01-13T22:02:20.978Z","repository":{"id":330804849,"uuid":"1123766781","full_name":"ankitkpandey1/uringcore","owner":"ankitkpandey1","description":"High-performance asyncio event loop for Python using io_uring - 36% faster than asyncio","archived":false,"fork":false,"pushed_at":"2026-01-03T15:38:39.000Z","size":382,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-09T03:47:03.668Z","etag":null,"topics":["asyncio","event-loop","high-performance","io-uring","networking","pyo3","rust"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ankitkpandey1.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-27T15:21:36.000Z","updated_at":"2026-01-08T04:54:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ankitkpandey1/uringcore","commit_stats":null,"previous_names":["ankitkpandey1/uringcore"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ankitkpandey1/uringcore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankitkpandey1%2Furingcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankitkpandey1%2Furingcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankitkpandey1%2Furingcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankitkpandey1%2Furingcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ankitkpandey1","download_url":"https://codeload.github.com/ankitkpandey1/uringcore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankitkpandey1%2Furingcore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","event-loop","high-performance","io-uring","networking","pyo3","rust"],"created_at":"2025-12-28T09:35:02.078Z","updated_at":"2026-01-13T22:02:20.973Z","avatar_url":"https://github.com/ankitkpandey1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# uringcore\n\n[![CI](https://github.com/ankitkpandey1/uringcore/actions/workflows/ci.yml/badge.svg)](https://github.com/ankitkpandey1/uringcore/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org/)\n\nA high-performance asyncio event loop for Linux using io_uring.\n\n\n`uringcore` is a high-performance, drop-in replacement for `asyncio` on Linux.\nIt passes **all tests** including proper stress testing and FastAPI/Starlette E2E tests, and outperforms `uvloop` in single-task latency benchmarks.\n\n\n## Key Features\n- **Pure io_uring**: No `epoll`/`selector` fallback. All I/O is submitted to the ring.\n- **Native Scheduler**: `Mutex\u003cVecDeque\u003e` for efficient single-threaded task scheduling.\n- **Zero-Copy Buffers**: Pre-registered fixed buffers for maximum I/O bandwidth.\n- **Native Futures**: Optimized Future implementation entirely in Rust.\n- **Asyncio Function Caching**: Cached `_enter_task`/`_leave_task` to reduce per-step overhead.\n- **Registered FD Table**: `IOSQE_FIXED_FILE` support for zero FD lookup overhead.\n- **Zero-Copy Send**: `IORING_OP_SEND_ZC` for large payload efficiency (kernel 6.0+).\n- **Optimistic Syscalls**: Direct non-blocking syscalls for UDP fast-path (830k+ ops/sec).\n- **Multishot Recv**: `RECV_MULTISHOT` for persistent connections (kernel 5.19+).\n- **Native Timers**: `IORING_OP_TIMEOUT` for zero-syscall timer management.\n- **Strict Resource Management**: Deterministic cleanup via `Drop` trait.\n\n## Benchmarks\nLatest results (Jan 2026) vs `uvloop`:\n\n**Single-Task Latency (uringcore wins):**\n- `sleep(0)`: **2.9x faster** (4.26µs vs 12.53µs)\n- `lock_acquire`: **3.1x faster** (3.90µs vs 12.26µs)\n- `future_res`: **3.3x faster** (3.91µs vs 12.81µs)\n\n**High-Concurrency (gather 100):**\n- `asyncio`: 173 µs\n- `uringcore`: **139 µs** (1.25x faster than asyncio)\n- `uvloop`: 105 µs (gap is purely FFI overhead, syscalls are minimized)\n\n## Performance Verification\n\nTo verify system efficiency (syscall reduction), `gather(100)` was profiled using `strace`.\n\n| Metric | uringcore | uvloop | Impact |\n|--------|-----------|--------|--------|\n| **Total Syscalls** | **1,979** | 52,587 | **26x reduction** |\n| `io_uring_enter` | 0 | 2,200 | Perfect batching |\n| `epoll_ctl` | 2 | 13,201 | Kernel thrashing prevented |\n\n**Reproduction:**\nRun the included benchmark with `strace` to reproduce these findings:\n\n```bash\n# Install strace\nsudo apt-get install strace\n\n# Run benchmark for uringcore\nstrace -c python3 benchmarks/syscall_bench.py uringcore\n\n# Run benchmark for uvloop\nstrace -c python3 benchmarks/syscall_bench.py uvloop\n```\n\n## Introduction\n\nuringcore provides a drop-in replacement for Python's asyncio event loop, built on the io_uring interface available in Linux kernel 5.11+ (with advanced features optimal on 5.19+). The project targets use cases where low-latency I/O and high throughput are critical requirements.\n\nThe implementation leverages a completion-driven architecture rather than the traditional readiness-based model used by epoll. This design reduces syscalls on the hot path (near-zero when SQPOLL is enabled), yielding measurable latency and CPU improvements.\n\n## Use Cases\n\n- **Real-time data pipelines** processing high message volumes\n- **API gateways** handling high concurrent connection counts\n- **WebSocket servers** with persistent connections\n- **Database connection pools** with intensive query workloads\n\n## Requirements\n\n- Linux kernel 5.11+ (5.19+ recommended for `RECV_MULTI` optimizations)\n- Python 3.10+\n- Rust 1.85+ (Edition 2024)\n\n**SQPOLL Mode:** Requires `CAP_SYS_ADMIN` or kernel 5.12+ with unprivileged SQPOLL. SQPOLL often requires elevated privileges and may be unavailable on managed/cloud hosts; uringcore auto-detects SQPOLL capability and falls back to batched `io_uring_enter` when unsupported. This fallback is automatic and requires no configuration.\n\n## Installation\n\n### From PyPI\n\n```bash\npip install uringcore\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/ankitkpandey1/uringcore.git\ncd uringcore\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install build dependencies\npip install maturin\n\n# Build and install\nmaturin develop\n```\n\n## Quick Start\n\nReplace the default asyncio event loop with uringcore:\n\n```python\nimport asyncio\nimport uringcore\n\n# Set the event loop policy\nasyncio.set_event_loop_policy(uringcore.EventLoopPolicy())\n\nasync def main():\n    # Standard asyncio code works unchanged\n    await asyncio.sleep(1)\n    print(\"Hello from uringcore!\")\n\nasyncio.run(main())\n```\n\n### With FastAPI\n\n```python\nimport asyncio\nimport uringcore\nfrom fastapi import FastAPI\n\nasyncio.set_event_loop_policy(uringcore.EventLoopPolicy())\n\napp = FastAPI()\n\n@app.get(\"/\")\nasync def root():\n    return {\"message\": \"Hello, World!\"}\n```\n\n### With Starlette\n\n```python\nimport asyncio\nimport uringcore\nfrom starlette.applications import Starlette\nfrom starlette.responses import JSONResponse\nfrom starlette.routing import Route\n\nasyncio.set_event_loop_policy(uringcore.EventLoopPolicy())\n\nasync def homepage(request):\n    return JSONResponse({\"hello\": \"world\"})\n\napp = Starlette(routes=[Route(\"/\", homepage)])\n```\n\n## Performance\n\nMeasured benchmark results against standard asyncio and uvloop. See [BENCHMARK.md](BENCHMARK.md) for machine specs, exact commands, and methodology.\n\n| Metric | uringcore | asyncio | uvloop |\n|--------|-----------|---------|--------|\n| **Throughput** | 15,394 req/s | 11,317 req/s | 11,721 req/s |\n| **p50 Latency** | 58 µs | 83 µs | 78 µs |\n| **p99 Latency** | 121 µs | 181 µs | 182 µs |\n| **vs asyncio** | **+36%** | baseline | +4% |\n\n## Features\n\n| Feature | Status | Notes |\n|---------|--------|-------|\n| **Core I/O on io_uring** | ✅ Stable | Primary implementation uses io_uring; configurable fallbacks (batched `io_uring_enter` or epoll) available for restricted environments |\n| **TCP** | ✅ Stable | `create_server`, `create_connection`, `start_server` |\n| **UDP** | ✅ Stable | `create_datagram_endpoint` |\n| **Unix Sockets** | ✅ Stable | `create_unix_server`, `create_unix_connection` |\n| **Signal Handlers** | ✅ Stable | `add_signal_handler`, `remove_signal_handler` |\n| **Executor** | ✅ Stable | `run_in_executor` for blocking calls |\n| **Reader/Writer** | ✅ Stable | `add_reader`, `add_writer` for compatibility |\n| **Subprocess** | 🔶 Beta | `subprocess_exec`, `subprocess_shell` |\n| **SSL/TLS** | 🔶 Beta | Memory BIO wrapper (kTLS not yet integrated) |\n| **IORING_OP_LINK_TIMEOUT** | 🔶 Beta | Connection timeout support |\n\n**Legend:** ✅ Stable (CI-tested) | 🔶 Beta (functional, limited testing)\n\n## Configuration\n\nDefault buffer pool settings (tunable via environment variables):\n\n| Setting | Default | Env Var |\n|---------|---------|---------|\n| Buffer size | 64 KB | `URINGCORE_BUFFER_SIZE` |\n| Buffer count | 1024 | `URINGCORE_BUFFER_COUNT` |\n| Quarantine window | 5 ms | `URINGCORE_QUARANTINE_MS` |\n\n## Project Structure\n\n```\nuringcore/\n├── src/                    # Rust core implementation\n│   ├── lib.rs              # PyO3 module entry point\n│   ├── buffer.rs           # Zero-copy buffer pool\n│   ├── ring.rs             # io_uring wrapper\n│   ├── state.rs            # FD state machine\n│   └── error.rs            # Error types\n├── python/                 # Python layer\n│   └── uringcore/\n│       ├── loop.py         # UringEventLoop\n│       ├── transport.py    # Socket transport\n│       ├── datagram.py     # UDP transport\n│       ├── subprocess.py   # Subprocess transport\n│       └── ssl_transport.py # SSL/TLS wrapper\n├── tests/                  # Test suites\n└── benchmarks/             # Performance benchmarks\n```\n\n## Documentation\n\n- [Architecture](ARCHITECTURE.md) - Design decisions, io_uring internals, CI test matrix\n- [Benchmarks](BENCHMARK.md) - Performance measurements with reproducibility metadata\n\n## Development\n\n### Running Tests\n\n```bash\n# Rust tests\ncargo test\n\n# Python tests\nsource .venv/bin/activate\npytest tests/ -v\n```\n\nCI runs tests across Python 3.10-3.13 and multiple kernel versions. See [`.github/workflows/ci.yml`](.github/workflows/ci.yml) for the test matrix.\n\n### Code Quality\n\n```bash\ncargo fmt \u0026\u0026 cargo clippy --all-targets -- -D warnings\n```\n\n## Security\n\n- **SQPOLL** requires `CAP_SYS_ADMIN` on kernels \u003c 5.12\n- **Seccomp**: If syscalls are blocked, uringcore falls back gracefully with diagnostic messages\n- **Containers**: Works in Docker/Podman with default seccomp profiles; restrictive profiles may require `--security-opt seccomp=unconfined`\n\nFor vulnerability reports, contact: ankitkpandey1@gmail.com\n\n## License\n\n```\nSPDX-License-Identifier: Apache-2.0\nCopyright 2024-2025 Ankit Kumar Pandey \u003cankitkpandey1@gmail.com\u003e\n```\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.\n\n## Author\n\n**Ankit Kumar Pandey** - [ankitkpandey1@gmail.com](mailto:ankitkpandey1@gmail.com)\n\n## Acknowledgments\n\n- The io_uring subsystem maintainers, particularly Jens Axboe\n- The PyO3 project for Rust-Python bindings\n- The uvloop project for demonstrating high-performance event loop implementation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankitkpandey1%2Furingcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fankitkpandey1%2Furingcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankitkpandey1%2Furingcore/lists"}