rusty-ring 0.2.0__tar.gz

rusty_ring-0.2.0/CLAUDE.md

@@ -0,0 +1,31 @@
+# rusty-ring
+
+## Purpose
+
+Rust-based io_uring bindings for Python via PyO3. Replaces the external `liburing` (Cython) dependency with bindings built on the `io-uring` crate from tokio-rs.
+
+## Layout
+
+```
+src/              # Rust source code
+python/rusty_ring/  # Python type stubs (maturin mixed layout)
+tests/            # Python tests
+pyproject.toml    # Package metadata (maturin build backend)
+Cargo.toml        # Rust package config
+```
+
+## Commands
+
+```bash
+just dev           # Build debug extension via maturin develop
+just dev-release   # Build release extension
+just test          # Run Python tests (builds first)
+just test-rust     # Run Rust tests
+just check         # Run all checks
+```
+
+## Notes
+
+- Uses maturin (not hatchling) as build backend
+- Not managed by copier/bonfire template
+- `src/` contains Rust code, not Python — Python stubs live in `python/`

rusty_ring-0.2.0/Cargo.lock

@@ -0,0 +1,197 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
+[[package]]
+name = "bitflags"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "io-uring"
+version = "0.7.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdd7bddefd0a8833b88a4b68f90dae22c7450d11b354198baee3874fd811b344"
+dependencies = [
+ "bitflags",
+ "cfg-if",
+ "libc",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.182"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6800badb6cb2082ffd7b6a67e6125bb39f18782f793520caee8cb8846be06112"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab53c047fcd1a1d2a8820fe84f05d6be69e9526be40cb03b73f86b6b03e6d87d"
+dependencies = [
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b455933107de8642b4487ed26d912c2d899dec6114884214a0b3bb3be9261ea6"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c85c9cbfaddf651b1221594209aed57e9e5cff63c4d11d1feead529b872a089"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0a5b10c9bf9888125d917fb4d2ca2d25c8df94c7ab5a52e13313a07e050a3b02"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "03b51720d314836e53327f5871d4c0cfb4fb37cc2c4a11cc71907a86342c40f9"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21b2ebcf727b7760c461f091f9f0f539b77b8e87f2fd88131e7f1b433b3cece4"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "rusty-ring"
+version = "0.1.0"
+dependencies = [
+ "io-uring",
+ "libc",
+ "pyo3",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+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 = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"

rusty_ring-0.2.0/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "rusty-ring"
+version = "0.1.0"
+edition = "2024"
+readme = "README.md"
+
+[lib]
+name = "rusty_ring"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.27", features = ["extension-module"] }
+io-uring = "0.7"
+libc = "0.2"

rusty_ring-0.2.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: rusty-ring
+Version: 0.2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Summary: Rust-based io_uring bindings via PyO3
+Keywords: io_uring,rust,pyo3,async,io,linux
+Author-email: Otto Sellerstam <ottosellerstam@gmail.com>
+License: MIT
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/otto-sellerstam/one-ring
+Project-URL: Issues, https://github.com/otto-sellerstam/one-ring/issues
+Project-URL: Repository, https://github.com/otto-sellerstam/one-ring
+
+# rusty-ring
+
+Rust-based `io_uring` bindings for Python via PyO3, built on the [`io-uring`](https://crates.io/crates/io-uring) crate from `tokio-rs`.
+

rusty_ring-0.2.0/README.md

@@ -0,0 +1,3 @@
+# rusty-ring
+
+Rust-based `io_uring` bindings for Python via PyO3, built on the [`io-uring`](https://crates.io/crates/io-uring) crate from `tokio-rs`.

rusty_ring-0.2.0/justfile

@@ -0,0 +1,34 @@
+# List available recipes
+default:
+    @just --list
+
+# Build the Rust extension (debug, for development)
+dev:
+    uv run maturin develop
+
+# Build the Rust extension (release)
+dev-release:
+    uv run maturin develop --release
+
+# Run tests (builds first)
+test: dev
+    uv run pytest tests/
+
+# Run clippy linter (fail on warnings)
+clippy:
+    cargo clippy -- -D warnings
+
+# Format Rust code
+fmt:
+    cargo fmt
+
+# Check Rust formatting
+fmt-check:
+    cargo fmt -- --check
+
+# Run Rust tests
+test-rust:
+    cargo test
+
+# Run all checks
+check: clippy fmt-check test-rust test

rusty_ring-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "rusty-ring"
+version = "0.2.0"
+description = "Rust-based io_uring bindings via PyO3"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [
+    { name = "Otto Sellerstam", email = "ottosellerstam@gmail.com" },
+]
+readme = "README.md"
+keywords = ["io_uring", "rust", "pyo3", "async", "io", "linux"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Rust",
+    "Topic :: System :: Networking",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/otto-sellerstam/one-ring"
+Repository = "https://github.com/otto-sellerstam/one-ring"
+Issues = "https://github.com/otto-sellerstam/one-ring/issues"
+
+[build-system]
+requires = ["maturin>=1.8,<2.0"]
+build-backend = "maturin"
+
+[tool.maturin]
+features = ["pyo3/extension-module"]
+python-source = "python"
+module-name = "rusty_ring._rusty_ring"

rusty_ring-0.2.0/python/rusty_ring/__init__.py

@@ -0,0 +1,121 @@
+from rusty_ring._rusty_ring import (
+    AF_INET,
+    AF_INET6,
+    AF_UNIX,
+    AT_EMPTY_PATH,
+    AT_FDCWD,
+    AT_SYMLINK_NOFOLLOW,
+    IPPROTO_TCP,
+    MSG_DONTWAIT,
+    MSG_NOSIGNAL,
+    O_APPEND,
+    O_CLOEXEC,
+    O_CREAT,
+    O_NONBLOCK,
+    O_RDONLY,
+    O_RDWR,
+    O_TRUNC,
+    O_WRONLY,
+    S_IFDIR,
+    S_IFIFO,
+    S_IFLNK,
+    S_IFMT,
+    S_IFREG,
+    S_IFSOCK,
+    S_IRGRP,
+    S_IROTH,
+    S_IRUSR,
+    S_IWGRP,
+    S_IWOTH,
+    S_IWUSR,
+    S_IXGRP,
+    S_IXOTH,
+    S_IXUSR,
+    SFD_CLOEXEC,
+    SFD_NONBLOCK,
+    SIGHUP,
+    SIGINT,
+    SIGTERM,
+    SO_KEEPALIVE,
+    SO_REUSEADDR,
+    SO_REUSEPORT,
+    SOCK_CLOEXEC,
+    SOCK_DGRAM,
+    SOCK_NONBLOCK,
+    SOCK_STREAM,
+    SOL_SOCKET,
+    STATX_ALL,
+    STATX_ATIME,
+    STATX_CTIME,
+    STATX_INO,
+    STATX_MODE,
+    STATX_MTIME,
+    STATX_SIZE,
+    STATX_TYPE,
+    TCP_NODELAY,
+    CompletionEvent,
+    Ring,
+    SockAddr,
+    StatxBuffer,
+)
+
+__all__ = [
+    "AF_INET",
+    "AF_INET6",
+    "AF_UNIX",
+    "AT_EMPTY_PATH",
+    "AT_FDCWD",
+    "AT_SYMLINK_NOFOLLOW",
+    "IPPROTO_TCP",
+    "MSG_DONTWAIT",
+    "MSG_NOSIGNAL",
+    "O_APPEND",
+    "O_CLOEXEC",
+    "O_CREAT",
+    "O_NONBLOCK",
+    "O_RDONLY",
+    "O_RDWR",
+    "O_TRUNC",
+    "O_WRONLY",
+    "SFD_CLOEXEC",
+    "SFD_NONBLOCK",
+    "SIGHUP",
+    "SIGINT",
+    "SIGTERM",
+    "SOCK_CLOEXEC",
+    "SOCK_DGRAM",
+    "SOCK_NONBLOCK",
+    "SOCK_STREAM",
+    "SOL_SOCKET",
+    "SO_KEEPALIVE",
+    "SO_REUSEADDR",
+    "SO_REUSEPORT",
+    "STATX_ALL",
+    "STATX_ATIME",
+    "STATX_CTIME",
+    "STATX_INO",
+    "STATX_MODE",
+    "STATX_MTIME",
+    "STATX_SIZE",
+    "STATX_TYPE",
+    "S_IFDIR",
+    "S_IFIFO",
+    "S_IFLNK",
+    "S_IFMT",
+    "S_IFREG",
+    "S_IFSOCK",
+    "S_IRGRP",
+    "S_IROTH",
+    "S_IRUSR",
+    "S_IWGRP",
+    "S_IWOTH",
+    "S_IWUSR",
+    "S_IXGRP",
+    "S_IXOTH",
+    "S_IXUSR",
+    "TCP_NODELAY",
+    "CompletionEvent",
+    "Ring",
+    "SockAddr",
+    "StatxBuffer",
+]

rusty_ring-0.2.0/python/rusty_ring/__init__.pyi

@@ -0,0 +1,169 @@
+import types
+from typing import Self
+
+class SockAddr:
+    @staticmethod
+    def v4(ip: str, port: int) -> SockAddr: ...
+    @staticmethod
+    def v6(ip: str, port: int) -> SockAddr: ...
+
+class CompletionEvent:
+    @property
+    def user_data(self) -> int: ...
+    @property
+    def res(self) -> int: ...
+    @property
+    def flags(self) -> int: ...
+
+class Ring:
+    def __init__(self, depth: int = 32) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: types.TracebackType | None,
+    ) -> bool: ...
+    def submit(self) -> int: ...
+    def peek(self) -> CompletionEvent | None: ...
+    def wait(self) -> CompletionEvent: ...
+    def prep_nop(self, user_data: int) -> None: ...
+    def prep_timeout(self, user_data: int, sec: int, nsec: int) -> None: ...
+    def prep_close(
+        self,
+        user_data: int,
+        fd: int,
+    ) -> None: ...
+    def prep_cancel(
+        self, user_data: int, target_user_data: int, flags: int = 0
+    ) -> None: ...
+    def prep_read(
+        self, user_data: int, fd: int, buf: bytearray, nbytes: int, offset: int
+    ) -> None: ...
+    def prep_write(self, user_data: int, fd: int, buf: bytes, offset: int) -> None: ...
+    def prep_openat(
+        self, user_data: int, path: str, flags: int, mode: int, dir_fd: int
+    ) -> None: ...
+    def prep_statx(
+        self,
+        user_data: int,
+        path: str,
+        buf: StatxBuffer,
+        flags: int,
+        mask: int,
+        dir_fd: int,
+    ) -> None: ...
+    def prep_socket(
+        self,
+        user_data: int,
+        domain: int,
+        sock_type: int,
+        protocol: int = 0,
+        flags: int = 0,
+    ) -> None: ...
+    def prep_socket_setopt(
+        self,
+        user_data: int,
+        fd: int,
+    ) -> None: ...
+    def prep_socket_bind(
+        self, user_data: int, fd: int, sock_addr: SockAddr
+    ) -> None: ...
+    def prep_socket_listen(self, user_data: int, fd: int, backlog: int) -> None: ...
+    def prep_socket_accept(self, user_data: int, fd: int) -> None: ...
+    def prep_socket_recv(
+        self, user_data: int, fd: int, buf: bytearray, flags: int = 0
+    ) -> None: ...
+    def prep_socket_send(
+        self, user_data: int, fd: int, buf: bytes, flags: int = 0
+    ) -> None: ...
+    def prep_socket_connect(
+        self, user_data: int, fd: int, sock_addr: SockAddr
+    ) -> None: ...
+
+class StatxBuffer:
+    def __init__(self) -> None: ...
+    @property
+    def size(self) -> int: ...
+    @property
+    def mtime_sec(self) -> int: ...
+    @property
+    def ino(self) -> int: ...
+    @property
+    def mode(self) -> int: ...
+
+# File open flags
+O_RDONLY: int
+O_WRONLY: int
+O_RDWR: int
+O_CREAT: int
+O_TRUNC: int
+O_APPEND: int
+O_NONBLOCK: int
+O_CLOEXEC: int
+
+# File mode bits (permissions)
+S_IRUSR: int
+S_IWUSR: int
+S_IXUSR: int
+S_IRGRP: int
+S_IWGRP: int
+S_IXGRP: int
+S_IROTH: int
+S_IWOTH: int
+S_IXOTH: int
+
+# File type bits
+S_IFREG: int
+S_IFDIR: int
+S_IFLNK: int
+S_IFSOCK: int
+S_IFIFO: int
+S_IFMT: int
+
+# AT flags (path resolution)
+AT_FDCWD: int
+AT_EMPTY_PATH: int
+AT_SYMLINK_NOFOLLOW: int
+
+# Statx mask
+STATX_TYPE: int
+STATX_MODE: int
+STATX_INO: int
+STATX_SIZE: int
+STATX_MTIME: int
+STATX_ATIME: int
+STATX_CTIME: int
+STATX_ALL: int
+
+# Socket: address families
+AF_INET: int
+AF_INET6: int
+AF_UNIX: int
+
+# Socket: types
+SOCK_STREAM: int
+SOCK_DGRAM: int
+SOCK_NONBLOCK: int
+SOCK_CLOEXEC: int
+
+# Socket: options
+SOL_SOCKET: int
+SO_REUSEADDR: int
+SO_REUSEPORT: int
+SO_KEEPALIVE: int
+IPPROTO_TCP: int
+TCP_NODELAY: int
+
+# Socket: send/recv flags
+MSG_NOSIGNAL: int
+MSG_DONTWAIT: int
+
+# Signals
+SIGINT: int
+SIGTERM: int
+SIGHUP: int
+
+# Signalfd flags
+SFD_NONBLOCK: int
+SFD_CLOEXEC: int

rusty_ring-0.2.0/src/lib.rs

@@ -0,0 +1,678 @@
+use io_uring::{IoUring, opcode, types};
+use pyo3::exceptions::{PyRuntimeError, PyValueError};
+use pyo3::prelude::*;
+use pyo3::types::{PyByteArray, PyBytes};
+use std::collections::HashMap;
+use std::ffi::CString;
+use std::net::{Ipv4Addr, Ipv6Addr};
+use std::os::unix::io::RawFd;
+
+/// A completed io_uring operation.
+#[pyclass(frozen)]
+#[derive(Clone, Debug)]
+struct CompletionEvent {
+    #[pyo3(get)]
+    user_data: u64,
+    #[pyo3(get)]
+    res: i32,
+    #[pyo3(get)]
+    flags: u32,
+}
+
+#[pymethods]
+impl CompletionEvent {
+    fn __repr__(&self) -> String {
+        format!(
+            "CompletionEvent(user_data={}, res={}, flags={})",
+            self.user_data, self.res, self.flags
+        )
+    }
+}
+
+#[allow(dead_code)]
+struct StatxRequest {
+    path: CString,
+    statxbuf: Py<StatxBuffer>,
+}
+
+/// Owns an io_uring instance and exposes prep/submit/complete operations.
+///
+/// Usage from Python:
+/// ```python
+///     with Ring(depth=32) as ring:
+///         ring.prep_nop(user_data=1)
+///         ring.submit()
+///         cqe = ring.wait()
+/// ```
+///
+#[pyclass]
+struct Ring {
+    ring: Option<IoUring>,
+    depth: u32,
+
+    /// Buffers that are currently owned by the kernel (between submit and CQE).
+    /// Keyed by `user_data` so they can be released when the CQE arrives.
+    ///
+    /// The kernel holds raw pointers into these buffers. They must be kept
+    /// alive and un-resized until the corresponding CQE is consumed.
+    /// TODO: Consolidate into 1.
+    pinned_mutable_buffers: HashMap<u64, Py<PyByteArray>>,
+
+    pinned_immutable_buffers: HashMap<u64, Py<PyBytes>>,
+
+    /// CStrings for paths passed to openat.
+    pinned_paths: HashMap<u64, CString>,
+
+    /// Timespecs for timeouts.
+    pinned_timespecs: HashMap<u64, types::Timespec>,
+
+    /// Addresses for sockets.
+    pinned_sockaddr: HashMap<u64, SockAddrInner>,
+
+    /// Socket option values. Boxed for pointer stability across HashMap resizes.
+    pinned_sockopts: HashMap<u64, Box<i32>>,
+
+    // Statx buffers
+    pinned_statx_buffers: HashMap<u64, StatxRequest>,
+}
+
+impl Ring {
+    fn uring_mut(&mut self) -> PyResult<&mut IoUring> {
+        self.ring
+            .as_mut()
+            .ok_or_else(|| PyRuntimeError::new_err("Ring not initialised (use as context manager)"))
+    }
+
+    /// Push an entry onto the SQ. Panics if SQ is full.
+    fn push_entry(&mut self, entry: io_uring::squeue::Entry) -> PyResult<()> {
+        let ring = self.uring_mut()?;
+        // SAFETY: we trust that the caller has set up the entry correctly and
+        // that any buffers referenced are pinned in `pinned_buffers`.
+        unsafe {
+            ring.submission()
+                .push(&entry)
+                .map_err(|_| PyRuntimeError::new_err("Submission queue is full"))?;
+        }
+        Ok(())
+    }
+
+    /// Release any pinned resources associated with a completed user_data.
+    fn release_pinned(&mut self, user_data: u64) {
+        self.pinned_mutable_buffers.remove(&user_data);
+        self.pinned_immutable_buffers.remove(&user_data);
+        self.pinned_paths.remove(&user_data);
+        self.pinned_sockaddr.remove(&user_data);
+        self.pinned_timespecs.remove(&user_data);
+        self.pinned_sockopts.remove(&user_data);
+        self.pinned_statx_buffers.remove(&user_data);
+    }
+
+    fn cqe_to_event(&mut self, cqe: &io_uring::cqueue::Entry) -> CompletionEvent {
+        let user_data = cqe.user_data();
+        self.release_pinned(user_data);
+        CompletionEvent {
+            user_data,
+            res: cqe.result(),
+            flags: cqe.flags(),
+        }
+    }
+}
+
+#[pymethods]
+impl Ring {
+    #[new]
+    #[pyo3(signature = (depth = 32))]
+    fn new(depth: u32) -> Self {
+        Ring {
+            ring: None,
+            depth,
+            pinned_mutable_buffers: HashMap::new(),
+            pinned_immutable_buffers: HashMap::new(),
+            pinned_paths: HashMap::new(),
+            pinned_timespecs: HashMap::new(),
+            pinned_sockaddr: HashMap::new(),
+            pinned_sockopts: HashMap::new(),
+            pinned_statx_buffers: HashMap::new(),
+        }
+    }
+
+    /// Python CM protocol.
+    fn __enter__(mut slf: PyRefMut<'_, Self>) -> PyResult<PyRefMut<'_, Self>> {
+        let ring = IoUring::new(slf.depth)
+            .map_err(|e| PyRuntimeError::new_err(format!("io_uring_setup failed: {e}")))?;
+        slf.ring = Some(ring);
+        Ok(slf)
+    }
+
+    #[pyo3(signature = (_exc_type=None, _exc_val=None, _exc_tb=None))]
+    fn __exit__(
+        &mut self,
+        _exc_type: Option<&Bound<'_, PyAny>>,
+        _exc_val: Option<&Bound<'_, PyAny>>,
+        _exc_tb: Option<&Bound<'_, PyAny>>,
+    ) -> PyResult<bool> {
+        self.pinned_mutable_buffers.clear();
+        self.pinned_immutable_buffers.clear();
+        self.pinned_paths.clear();
+        self.pinned_sockaddr.clear();
+        self.pinned_timespecs.clear();
+        self.pinned_sockopts.clear();
+        self.pinned_statx_buffers.clear();
+        self.ring = None; // Drop triggers internal io_uring cleanup
+        Ok(false)
+    }
+
+    /// Submit all queued SQEs to the kernel. Returns number submitted.
+    fn submit(&mut self) -> PyResult<u32> {
+        let n = self
+            .uring_mut()?
+            .submit()
+            .map_err(|e| PyRuntimeError::new_err(format!("io_uring_submit failed: {e}")))?;
+        Ok(n as u32)
+    }
+
+    /// Non-blocking peek.
+    fn peek(&mut self) -> PyResult<Option<CompletionEvent>> {
+        let ring = self.uring_mut()?;
+        let cq = ring.completion();
+        let cqe = cq.into_iter().next();
+        match cqe {
+            Some(cqe) => Ok(Some(self.cqe_to_event(&cqe))),
+            None => Ok(None),
+        }
+    }
+
+    /// Blocking wait for at least one CQE and return it.
+    fn wait(&mut self, py: Python<'_>) -> PyResult<CompletionEvent> {
+        let ring = self.uring_mut()?;
+        py.detach(|| ring.submit_and_wait(1))
+            .map_err(|e| PyRuntimeError::new_err(format!("io_uring_wait failed: {e}")))?;
+        let cqe = ring
+            .completion()
+            .next()
+            .ok_or_else(|| PyRuntimeError::new_err("No CQE after wait"))?;
+        Ok(self.cqe_to_event(&cqe))
+    }
+
+    /// Submit a no-op.
+    fn prep_nop(&mut self, user_data: u64) -> PyResult<()> {
+        let entry = opcode::Nop::new().build().user_data(user_data);
+        self.push_entry(entry)
+    }
+
+    /// Submit a timeout (sleep).
+    fn prep_timeout(&mut self, user_data: u64, sec: u64, nsec: u32) -> PyResult<()> {
+        let timespec = types::Timespec::new().sec(sec).nsec(nsec);
+        self.pinned_timespecs.insert(user_data, timespec);
+        let ts = self.pinned_timespecs.get(&user_data).unwrap();
+
+        let entry = opcode::Timeout::new(ts).build().user_data(user_data);
+
+        self.push_entry(entry)
+    }
+
+    /// Prep a read into `buf`.
+    /// The `buf` (a Python `bytearray`) is pinned until the CQE is consumed.
+    /// **Do not resize `buf` between prep and consuming the CQE.**
+    #[pyo3(signature = (user_data, fd, buf, nbytes, offset))]
+    fn prep_read(
+        &mut self,
+        _py: Python<'_>,
+        user_data: u64,
+        fd: RawFd,
+        buf: Bound<'_, PyByteArray>,
+        nbytes: u32,
+        offset: u64,
+    ) -> PyResult<()> {
+        let ptr = buf.data();
+        let len = nbytes.min(buf.len() as u32);
+
+        let entry = opcode::Read::new(types::Fd(fd), ptr.cast(), len)
+            .offset(offset)
+            .build()
+            .user_data(user_data);
+
+        self.pinned_mutable_buffers.insert(user_data, buf.unbind());
+        self.push_entry(entry)
+    }
+
+    // Prepares statx for metadata extraction.
+    fn prep_statx(
+        &mut self,
+        user_data: u64,
+        path: &str,
+        buf: Bound<'_, StatxBuffer>,
+        flags: i32,
+        mask: u32,
+        dir_fd: RawFd,
+    ) -> PyResult<()> {
+        let c_path =
+            CString::new(path).map_err(|_| PyRuntimeError::new_err("Path contains null byte"))?;
+        let path_ptr = c_path.as_ptr();
+
+        let mut guard = buf.borrow_mut();
+        let statxbuf_ptr = &mut *guard.inner as *mut libc::statx as *mut io_uring::types::statx;
+
+        let entry = opcode::Statx::new(types::Fd(dir_fd), path_ptr, statxbuf_ptr)
+            .flags(flags)
+            .mask(mask)
+            .build()
+            .user_data(user_data);
+
+        drop(guard);
+
+        self.pinned_statx_buffers.insert(
+            user_data,
+            StatxRequest {
+                path: c_path,
+                statxbuf: buf.unbind(),
+            },
+        );
+        self.push_entry(entry)
+    }
+
+    /// Prep a file write.
+    #[pyo3(signature = (user_data, fd, buf, offset))]
+    fn prep_write(
+        &mut self,
+        _py: Python<'_>,
+        user_data: u64,
+        fd: RawFd,
+        buf: Bound<'_, PyBytes>,
+        offset: u64,
+    ) -> PyResult<()> {
+        let data = buf.as_bytes();
+        let ptr = data.as_ptr();
+        let len = data.len() as u32;
+
+        let entry = opcode::Write::new(types::Fd(fd), ptr.cast(), len)
+            .offset(offset)
+            .build()
+            .user_data(user_data);
+
+        self.pinned_immutable_buffers
+            .insert(user_data, buf.unbind());
+        self.push_entry(entry)
+    }
+
+    /// Prep a file open.
+    #[pyo3(signature = (user_data, path, flags, mode, dir_fd))]
+    fn prep_openat(
+        &mut self,
+        user_data: u64,
+        path: &str,
+        flags: i32,
+        mode: u32,
+        dir_fd: RawFd,
+    ) -> PyResult<()> {
+        let c_path =
+            CString::new(path).map_err(|_| PyRuntimeError::new_err("Path contains null byte"))?;
+        let ptr = c_path.as_ptr();
+
+        let entry = opcode::OpenAt::new(types::Fd(dir_fd), ptr)
+            .flags(flags)
+            .mode(mode)
+            .build()
+            .user_data(user_data);
+
+        // Pin the CString so the pointer stays valid until CQE
+        self.pinned_paths.insert(user_data, c_path);
+        self.push_entry(entry)
+    }
+
+    /// Prep a file/socket close.
+    fn prep_close(&mut self, user_data: u64, fd: RawFd) -> PyResult<()> {
+        let entry = opcode::Close::new(types::Fd(fd))
+            .build()
+            .user_data(user_data);
+        self.push_entry(entry)
+    }
+
+    /// Prep a cancellation of another in-flight operation.
+    #[pyo3(signature = (user_data, target_user_data, flags = 0))]
+    fn prep_cancel(&mut self, user_data: u64, target_user_data: u64, flags: i32) -> PyResult<()> {
+        let entry = opcode::AsyncCancel::new(target_user_data)
+            .build()
+            .user_data(user_data);
+        // TODO: use flags once io-uring crate exposes cancel flags
+        let _ = flags;
+        self.push_entry(entry)
+    }
+
+    /// Prep a socket creation.
+    #[pyo3(signature = (user_data, domain, sock_type, protocol = 0, flags = 0))]
+    fn prep_socket(
+        &mut self,
+        user_data: u64,
+        domain: i32,
+        sock_type: i32,
+        protocol: i32,
+        flags: u32,
+    ) -> PyResult<()> {
+        let entry = opcode::Socket::new(domain, sock_type, protocol)
+            .build()
+            .user_data(user_data);
+        let _ = flags; // TODO: pass flags if opcode supports it
+        self.push_entry(entry)
+    }
+
+    /// Prep a recv from a connected socket into `buf`.
+    #[pyo3(signature = (user_data, fd, buf, flags = 0))]
+    fn prep_socket_recv(
+        &mut self,
+        _py: Python<'_>,
+        user_data: u64,
+        fd: RawFd,
+        buf: Bound<'_, PyByteArray>,
+        flags: u32,
+    ) -> PyResult<()> {
+        let ptr = buf.data();
+        let len = buf.len() as u32;
+
+        let entry = opcode::Recv::new(types::Fd(fd), ptr.cast(), len)
+            .flags(flags as i32)
+            .build()
+            .user_data(user_data);
+
+        self.pinned_mutable_buffers.insert(user_data, buf.unbind());
+        self.push_entry(entry)
+    }
+
+    /// Prep a send to a connected socket.
+    #[pyo3(signature = (user_data, fd, buf, flags = 0))]
+    fn prep_socket_send(
+        &mut self,
+        _py: Python<'_>,
+        user_data: u64,
+        fd: RawFd,
+        buf: Bound<'_, PyBytes>,
+        flags: u32,
+    ) -> PyResult<()> {
+        let data = buf.as_bytes();
+        let ptr = data.as_ptr();
+        let len = data.len() as u32;
+
+        let entry = opcode::Send::new(types::Fd(fd), ptr.cast(), len)
+            .flags(flags as i32)
+            .build()
+            .user_data(user_data);
+
+        self.pinned_immutable_buffers
+            .insert(user_data, buf.unbind());
+        self.push_entry(entry)
+    }
+
+    /// Preps to bind to a socket.
+    fn prep_socket_bind(
+        &mut self,
+        _py: Python<'_>,
+        user_data: u64,
+        fd: RawFd,
+        sock_addr: SockAddr,
+    ) -> PyResult<()> {
+        self.pinned_sockaddr.insert(user_data, sock_addr.inner);
+
+        let stored = self.pinned_sockaddr.get(&user_data).unwrap();
+        let (ptr, len) = stored.as_ptr_and_len();
+
+        let entry = opcode::Bind::new(types::Fd(fd), ptr, len)
+            .build()
+            .user_data(user_data);
+
+        self.push_entry(entry)
+    }
+
+    /// Prepares a socket to listen. Marks it as passive.
+    fn prep_socket_listen(
+        &mut self,
+        _py: Python<'_>,
+        user_data: u64,
+        fd: RawFd,
+        backlog: i32,
+    ) -> PyResult<()> {
+        let entry = opcode::Listen::new(types::Fd(fd), backlog)
+            .build()
+            .user_data(user_data);
+
+        self.push_entry(entry)
+    }
+
+    /// Prepares a socket to accept an incoming connection.
+    /// TODO: Add sockaddr for kernel to fill, for logging who connected.
+    fn prep_socket_accept(&mut self, _py: Python<'_>, user_data: u64, fd: RawFd) -> PyResult<()> {
+        let entry = opcode::Accept::new(types::Fd(fd), std::ptr::null_mut(), std::ptr::null_mut())
+            .build()
+            .user_data(user_data);
+
+        self.push_entry(entry)
+    }
+
+    /// Connects to a socket from a client.
+    fn prep_socket_connect(
+        &mut self,
+        _py: Python<'_>,
+        user_data: u64,
+        fd: RawFd,
+        sock_addr: SockAddr,
+    ) -> PyResult<()> {
+        self.pinned_sockaddr.insert(user_data, sock_addr.inner);
+
+        let stored = self.pinned_sockaddr.get(&user_data).unwrap();
+        let (ptr, len) = stored.as_ptr_and_len();
+
+        let entry = opcode::Connect::new(types::Fd(fd), ptr, len)
+            .build()
+            .user_data(user_data);
+
+        self.push_entry(entry)
+    }
+
+    /// Set socket options.
+    fn prep_socket_setopt(&mut self, user_data: u64, fd: RawFd) -> PyResult<()> {
+        // TODO: Hardcoded for now.
+        let optval = Box::new(1i32); // SO_REUSEADDR value
+        self.pinned_sockopts.insert(user_data, optval);
+        let pinned = self.pinned_sockopts.get(&user_data).unwrap();
+
+        let entry = opcode::SetSockOpt::new(
+            types::Fd(fd),
+            libc::SOL_SOCKET as u32,
+            libc::SO_REUSEADDR as u32,
+            pinned.as_ref() as *const i32 as *const libc::c_void,
+            std::mem::size_of::<i32>() as u32,
+        )
+        .build()
+        .user_data(user_data);
+
+        self.push_entry(entry)
+    }
+}
+
+//TODO: Move to another module.
+#[derive(Clone)]
+enum SockAddrInner {
+    V4(libc::sockaddr_in),
+    V6(libc::sockaddr_in6),
+}
+
+impl SockAddrInner {
+    /// Returns address as pointer as well as its length.
+    fn as_ptr_and_len(&self) -> (*const libc::sockaddr, u32) {
+        match &self {
+            SockAddrInner::V4(addr) => (
+                addr as *const libc::sockaddr_in as *const libc::sockaddr,
+                std::mem::size_of::<libc::sockaddr_in>() as u32,
+            ),
+            SockAddrInner::V6(addr) => (
+                addr as *const libc::sockaddr_in6 as *const libc::sockaddr,
+                std::mem::size_of::<libc::sockaddr_in6>() as u32,
+            ),
+        }
+    }
+}
+
+#[pyclass]
+#[derive(Clone)]
+struct SockAddr {
+    inner: SockAddrInner,
+}
+
+#[pymethods]
+impl SockAddr {
+    #[staticmethod]
+    fn v4(ip: &str, port: u16) -> PyResult<Self> {
+        let addr_parsed: Ipv4Addr = ip
+            .parse()
+            .map_err(|e| PyValueError::new_err(format!("Invalid IPv4 address: {e}")))?;
+
+        let mut addr: libc::sockaddr_in = unsafe { std::mem::zeroed() };
+        addr.sin_family = libc::AF_INET as u16;
+        addr.sin_addr.s_addr = u32::from_ne_bytes(addr_parsed.octets());
+        addr.sin_port = port.to_be();
+        Ok(SockAddr {
+            inner: SockAddrInner::V4(addr),
+        })
+    }
+
+    #[staticmethod]
+    fn v6(ip: &str, port: u16) -> PyResult<Self> {
+        let addr_parsed: Ipv6Addr = ip
+            .parse()
+            .map_err(|e| PyValueError::new_err(format!("Invalid IPv6 address: {e}")))?;
+
+        let mut addr: libc::sockaddr_in6 = unsafe { std::mem::zeroed() };
+        addr.sin6_family = libc::AF_INET6 as u16;
+        addr.sin6_addr.s6_addr = addr_parsed.octets();
+        addr.sin6_port = port.to_be();
+        Ok(SockAddr {
+            inner: SockAddrInner::V6(addr),
+        })
+    }
+}
+
+#[pyclass]
+#[derive(Clone, Debug)]
+struct StatxBuffer {
+    inner: Box<libc::statx>,
+}
+
+#[pymethods]
+impl StatxBuffer {
+    #[new]
+    fn new() -> Self {
+        StatxBuffer {
+            inner: Box::new(unsafe { std::mem::zeroed() }),
+        }
+    }
+
+    #[getter]
+    fn size(&self) -> u64 {
+        self.inner.stx_size
+    }
+
+    #[getter]
+    fn mtime_sec(&self) -> i64 {
+        self.inner.stx_mtime.tv_sec
+    }
+
+    #[getter]
+    fn ino(&self) -> u64 {
+        self.inner.stx_ino
+    }
+
+    #[getter]
+    fn mode(&self) -> u32 {
+        self.inner.stx_mode as u32
+    }
+}
+
+fn register_constants(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    // File open flags
+    m.add("O_RDONLY", libc::O_RDONLY)?;
+    m.add("O_WRONLY", libc::O_WRONLY)?;
+    m.add("O_RDWR", libc::O_RDWR)?;
+    m.add("O_CREAT", libc::O_CREAT)?;
+    m.add("O_TRUNC", libc::O_TRUNC)?;
+    m.add("O_APPEND", libc::O_APPEND)?;
+    m.add("O_NONBLOCK", libc::O_NONBLOCK)?;
+    m.add("O_CLOEXEC", libc::O_CLOEXEC)?;
+
+    // File mode bits (permissions)
+    m.add("S_IRUSR", libc::S_IRUSR)?;
+    m.add("S_IWUSR", libc::S_IWUSR)?;
+    m.add("S_IXUSR", libc::S_IXUSR)?;
+    m.add("S_IRGRP", libc::S_IRGRP)?;
+    m.add("S_IWGRP", libc::S_IWGRP)?;
+    m.add("S_IXGRP", libc::S_IXGRP)?;
+    m.add("S_IROTH", libc::S_IROTH)?;
+    m.add("S_IWOTH", libc::S_IWOTH)?;
+    m.add("S_IXOTH", libc::S_IXOTH)?;
+
+    // File type bits (from st_mode / stx_mode)
+    m.add("S_IFREG", libc::S_IFREG)?;
+    m.add("S_IFDIR", libc::S_IFDIR)?;
+    m.add("S_IFLNK", libc::S_IFLNK)?;
+    m.add("S_IFSOCK", libc::S_IFSOCK)?;
+    m.add("S_IFIFO", libc::S_IFIFO)?;
+    m.add("S_IFMT", libc::S_IFMT)?;
+
+    // AT flags (path resolution)
+    m.add("AT_FDCWD", libc::AT_FDCWD)?;
+    m.add("AT_EMPTY_PATH", libc::AT_EMPTY_PATH)?;
+    m.add("AT_SYMLINK_NOFOLLOW", libc::AT_SYMLINK_NOFOLLOW)?;
+
+    // Statx mask (which fields to populate)
+    m.add("STATX_TYPE", libc::STATX_TYPE)?;
+    m.add("STATX_MODE", libc::STATX_MODE)?;
+    m.add("STATX_INO", libc::STATX_INO)?;
+    m.add("STATX_SIZE", libc::STATX_SIZE)?;
+    m.add("STATX_MTIME", libc::STATX_MTIME)?;
+    m.add("STATX_ATIME", libc::STATX_ATIME)?;
+    m.add("STATX_CTIME", libc::STATX_CTIME)?;
+    m.add("STATX_ALL", libc::STATX_ALL)?;
+
+    // Socket: address families
+    m.add("AF_INET", libc::AF_INET)?;
+    m.add("AF_INET6", libc::AF_INET6)?;
+    m.add("AF_UNIX", libc::AF_UNIX)?;
+
+    // Socket: types
+    m.add("SOCK_STREAM", libc::SOCK_STREAM)?;
+    m.add("SOCK_DGRAM", libc::SOCK_DGRAM)?;
+    m.add("SOCK_NONBLOCK", libc::SOCK_NONBLOCK)?;
+    m.add("SOCK_CLOEXEC", libc::SOCK_CLOEXEC)?;
+
+    // Socket: protocol levels and options
+    m.add("SOL_SOCKET", libc::SOL_SOCKET)?;
+    m.add("SO_REUSEADDR", libc::SO_REUSEADDR)?;
+    m.add("SO_REUSEPORT", libc::SO_REUSEPORT)?;
+    m.add("SO_KEEPALIVE", libc::SO_KEEPALIVE)?;
+    m.add("IPPROTO_TCP", libc::IPPROTO_TCP)?;
+    m.add("TCP_NODELAY", libc::TCP_NODELAY)?;
+
+    // Socket: send/recv flags
+    m.add("MSG_NOSIGNAL", libc::MSG_NOSIGNAL)?;
+    m.add("MSG_DONTWAIT", libc::MSG_DONTWAIT)?;
+
+    // Signals
+    m.add("SIGINT", libc::SIGINT)?;
+    m.add("SIGTERM", libc::SIGTERM)?;
+    m.add("SIGHUP", libc::SIGHUP)?;
+
+    // Signalfd flags
+    m.add("SFD_NONBLOCK", libc::SFD_NONBLOCK)?;
+    m.add("SFD_CLOEXEC", libc::SFD_CLOEXEC)?;
+
+    Ok(())
+}
+
+#[pymodule]
+fn _rusty_ring(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<Ring>()?;
+    m.add_class::<CompletionEvent>()?;
+    m.add_class::<SockAddr>()?;
+    m.add_class::<StatxBuffer>()?;
+
+    register_constants(m)?;
+    Ok(())
+}

rusty_ring-0.2.0/src/main.rs

@@ -0,0 +1,3 @@
+fn main() {
+    println!("Hello, world!");
+}

rusty_ring-0.2.0/tests/test_ring.py

@@ -0,0 +1,77 @@
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import TYPE_CHECKING
+
+from one_ring_loop.log import get_logger
+from rusty_ring import Ring
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+logger = get_logger(__name__)
+
+SERVER_MESSAGE = b"A new client connected!"
+
+
+class TestRing:
+    def test_ring_context_manager(self) -> None:
+        with Ring(32) as ring:
+            assert isinstance(ring, Ring)
+
+    def test_file_open_write_read(self, tmp_file_path: Path) -> None:
+        file_content = b"Hello! :)"
+
+        with Ring(32) as ring:
+            ring.prep_openat(
+                user_data=0, path=str(tmp_file_path), flags=66, mode=432, dir_fd=-100
+            )
+            ring.submit()
+            open_event = ring.wait()
+            logger.info("Got open event", io_event=open_event)
+            fd = open_event.res
+
+            write_buf = bytes(file_content)
+            ring.prep_write(0, fd=fd, buf=write_buf, offset=0)
+            ring.submit()
+            write_event = ring.wait()
+            logger.info("Got write event", io_event=write_event)
+
+            read_buf = bytearray(9)
+            ring.prep_read(0, fd=fd, buf=read_buf, nbytes=9, offset=0)
+            ring.submit()
+            read_event = ring.wait()
+            logger.info("Got read event", io_event=read_event)
+            assert bytes(read_buf) == file_content
+
+    def test_timeout(self, timing) -> None:
+        with Ring(32) as ring:
+            sleep_for_sec = 1
+            sleep_for_nsec = int(5e8)  # 0.5 seconds.
+            ring.prep_timeout(0, sleep_for_sec, sleep_for_nsec)
+            ring.submit()
+
+            timing.start()
+            ring.wait()
+            timing.assert_elapsed_between(1.5, 1.6, msg="Should sleep for 2 secounds")
+
+    def test_wait_does_not_hold_gil(self) -> None:
+        flag = threading.Event()
+
+        def background() -> None:
+            logger.info("Sleeping for 0.5 seconds")
+            time.sleep(0.5)
+            logger.info("Setting flag")
+            flag.set()
+
+        with Ring(32) as ring, ThreadPoolExecutor(max_workers=2) as executor:
+            ring.prep_timeout(0, sec=1, nsec=0)
+            ring.submit()
+
+            logger.info("Submitting background function")
+            executor.submit(background)
+            logger.info("Waiting on ring timeout")
+            ring.wait()
+            logger.info("Finished waiting")
+
+            assert flag.is_set()