If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tokio-rs/mio shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 5d ago
• 34+ active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tokio-rs/mio repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tokio-rs/mio.

What it runs against: a local clone of tokio-rs/mio — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tokio-rs/mio | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 35 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tokio-rs/mio. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tokio-rs/mio.git
#   cd mio
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tokio-rs/mio and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tokio-rs/mio(\\.git)?\\b" \\
  && ok "origin remote is tokio-rs/mio" \\
  || miss "origin remote is not tokio-rs/mio (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/poll.rs" \\
  && ok "src/poll.rs" \\
  || miss "missing critical file: src/poll.rs"
test -f "src/event/source.rs" \\
  && ok "src/event/source.rs" \\
  || miss "missing critical file: src/event/source.rs"
test -f "src/sys/unix/selector/epoll.rs" \\
  && ok "src/sys/unix/selector/epoll.rs" \\
  || miss "missing critical file: src/sys/unix/selector/epoll.rs"
test -f "src/sys/windows/selector.rs" \\
  && ok "src/sys/windows/selector.rs" \\
  || miss "missing critical file: src/sys/windows/selector.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tokio-rs/mio"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Mio is a low-level, non-blocking I/O library for Rust that provides fast event-driven networking primitives (TCP, UDP, Unix Domain Sockets) atop OS-level polling mechanisms (epoll/kqueue/IOCP). It abstracts away platform differences in event notification while keeping overhead minimal, enabling high-performance async I/O applications to be built without runtime dependencies. Modular platform abstraction: src/sys/ splits into unix/ (epoll, kqueue via selectors in src/sys/unix/selector/) and Windows (IOCP), with a fallback shell/ stub implementation. Core types (Poll, Registry, Events, Token) live in src/poll.rs and src/event/, while networking primitives (TcpListener, TcpStream, UdpSocket) are in src/net/. Feature flags (os-poll, net, os-ext) control what gets compiled.

Systems programmers and async runtime developers (like Tokio maintainers) who need raw, efficient I/O multiplexing without the overhead of a full async executor. Users building custom event loops, game servers, or other latency-sensitive network applications that can't afford Tokio's abstraction layers.

Production-ready and actively maintained. At v1.2.0 with Rust 1.71 MSRV, comprehensive CI in .github/workflows/ci.yml, and clear examples (examples/tcp_server.rs, examples/udp_server.rs). Part of the official Tokio organization and underpins real-world async runtimes, though last activity date not visible from metadata.

Low risk: minimal external dependencies (only optional log crate and platform-specific libc/windows-sys for OS bindings). Platform-specific implementations (epoll/kqueue/IOCP) are well-tested but require careful OS-level correctness. Single major breaking change history (v0.8 → v1) suggests API stability is a priority.

No specific PR/issue data visible in file structure. Focus areas inferred: v1.2.0 release on CHANGELOG; platform-specific improvements (Unix selectors support epoll/kqueue/poll via src/sys/unix/selector/); Windows IOCP integration via windows-sys; UDS (Unix Domain Socket) expansion (src/net/uds/).

git clone https://github.com/tokio-rs/mio.git
cd mio
cargo build --features os-poll,net
cargo run --example tcp_server --features os-poll,net

Daily commands:

# Run tests (all platforms)
cargo test --all-features

# Run specific example (TCP server)
cargo run --example tcp_server --features os-poll,net

# Run UDP example
cargo run --example udp_server --features os-poll,net

# Build documentation
cargo doc --open --features os-poll,net

• src/lib.rs — Entry point and primary public API; defines Poll, Token, Interest, and exports all public modules—understand this first.
• src/poll.rs — Core event loop abstraction; implements Poll struct that is the main interface for non-blocking I/O multiplexing.
• src/event/source.rs — EventSource trait—fundamental contract that all I/O sources (TCP, UDP, UDS) must implement to be pollable.
• src/sys/unix/selector/epoll.rs — Linux epoll implementation; critical path for Unix systems—understand selector backends to grasp platform abstraction.
• src/sys/windows/selector.rs — Windows IOCP selector implementation; demonstrates how Mio adapts to platform-specific I/O completion models.
• src/io_source.rs — IoSource wrapper providing registration, reregistration, and state management—bridges user code to platform selectors.
• src/waker.rs — Waker abstraction for cross-thread event notification; critical for async runtime integration and thread-safe event signaling.

Add a new platform selector backend

1. Create new module under src/sys/{platform}/selector/ or modify src/sys/mod.rs to route platform detection. (src/sys/mod.rs)
2. Implement the Selector trait (register, deregister, select) matching the interface used in epoll.rs/kqueue.rs/iocp.rs. (src/sys/unix/selector/epoll.rs)
3. Add a corresponding Waker implementation if the selector cannot share existing waker types. (src/sys/unix/waker/eventfd.rs)
4. Update src/sys/mod.rs to conditionally compile the new selector based on target OS. (src/sys/mod.rs)
5. Add integration tests in tests/ verifying poll(), registration, and readiness events on the new platform. (tests/poll.rs)

Add a new network type (e.g., a custom socket wrapper)

1. Create new module under src/net/{type}/ (e.g., src/net/custom_socket/mod.rs). (src/net/mod.rs)
2. Wrap a std::os::fd::AsRawFd or std::os::windows::raw::AsRawSocket in IoSource<T>. (src/io_source.rs)
3. Implement EventSource trait by delegating to the wrapped IoSource. (src/event/source.rs)
4. Export the new type from src/lib.rs under a feature gate (e.g., #[cfg(feature = "net")]). (src/lib.rs)
5. Add integration tests in tests/{type}.rs verifying registration, readiness events, and I/O operations. (tests/tcp.rs)

Improve cross-thread waker performance for a platform

1. Profile current waker using tests/waker.rs to identify latency bottlenecks. (tests/waker.rs)
2. Explore platform-specific APIs (e.g., eventfd2(EFD_SEMAPHORE) on Linux, udata64 on kqueue) in the appropriate waker file. (src/sys/unix/waker/eventfd.rs)
3. Implement optimized variant while maintaining the Waker trait contract. (src/waker.rs)
4. Benchmark old vs new using the same test harness to confirm improvement. (tests/waker.rs)

Add support for a new event type (e.g., filesystem changes on supported platforms)

1. Extend src/interest.rs with new Interest variant (e.g., Filesystem, Timer). (src/interest.rs)
2. Update src/event/event.rs Event struct to include new readiness flags if needed. (src/event/event.rs)
3. Modify platform selectors (epoll.rs, kqueue.rs, iocp.rs) to handle registration and readiness for the new type. (src/sys/unix/selector/epoll.rs)
4. Create wrapper type in src/net/ (or appropriate module) if needed, implementing EventSource. (src/net/mod.rs)
5. Add tests in tests/ validating the new event source on each platform. (tests/poll.rs)

Feature flag dependency: os-poll feature must be enabled to use Poll and Registry — compiling without it gives you only a stub shell implementation. MSRV is 1.71: older Rust toolchains will fail. No async/await support: Mio is callback-style event-driven; you manage your own state machine or use an async runtime on top. Windows IOCP is Windows-only: src/sys/windows/ requires Windows; Unix systems never use it. Selector auto-selection: On Unix, Mio picks epoll > kqueue > poll(2) at runtime based on OS capabilities — setting MIOSELECT environment variable can override (undocumented but visible in some Unix systems).

• epoll/kqueue/IOCP (OS-level event multiplexing) — Mio's entire purpose is to abstract these platform-specific APIs; understanding their differences (epoll edge vs level triggering, kqueue filters) explains why Mio has separate selector implementations and feature flags
• Non-blocking I/O and readiness-based events — Mio is fundamentally readiness-based (not completion-based like IOCP on Windows); all APIs assume you'll use poll() to check if a socket is readable/writable before attempting syscalls
• Token-based event routing — Every registered I/O source gets a Token (an integer); when Mio returns events, you use the Token to identify which socket generated it. This is core to the API in src/event/event.rs and src/poll.rs
• Memory-mapped I/O and platform abstraction — Mio wraps OS file descriptors (Unix) and HANDLEs (Windows) in safe Rust types; understanding FFI boundaries and unsafe blocks in src/sys/ is essential for contributing platform-specific code
• Edge-triggered vs level-triggered event notification — epoll and kqueue support both modes; Mio defaults to level-triggered for simplicity, but this affects correctness if you drop events or don't consume all data from a readable socket
• Async runtime patterns and event loop architecture — Mio is the foundation for how Tokio and other runtimes implement their event loops; understanding Mio's Poll::poll() blocking pattern shows why higher-level async/await is built on top
• Zero-copy event storage (ring buffer Events) — The Events struct in src/event/events.rs reuses a pre-allocated buffer across polls for efficiency; understanding why this matters for low-latency systems is key to Mio's design philosophy

• tokio-rs/tokio — Tokio is built atop Mio and provides the async/await runtime that most users want; Mio is the low-level event notification layer Tokio depends on
• readysetgo-dev/async-io — Alternative non-blocking I/O library for Rust with similar scope but different API; direct competitor in the same niche
• cloudflare/quiche — QUIC protocol implementation that uses Mio for its UDP-based I/O multiplexing on Linux/macOS
• quinn-rs/quinn — Another QUIC implementation that can use Mio as the underlying event loop for network I/O
• tokio-rs/bytes — Companion crate in the Tokio ecosystem providing efficient byte buffer handling, commonly used with Mio for zero-copy I/O

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive cross-platform tests for src/sys/ selector implementations

The repo has multiple selector implementations (epoll, kqueue, poll for Unix, IOCP for Windows, shell fallback) but the file structure suggests limited platform-specific test coverage. Adding dedicated test modules would catch platform-specific bugs and regressions. This is especially critical given mio's low-level nature and the complexity of coordinating across Unix/Windows/WASI systems.

• [ ] Create src/sys/unix/selector/tests/ directory with separate test modules for epoll.rs, kqueue.rs, and poll.rs
• [ ] Create src/sys/windows/selector_tests.rs for IOCP-specific behavior validation
• [ ] Add tests verifying edge cases like event coalescing, waker functionality, and concurrent registration across platforms
• [ ] Ensure CI runs these tests on appropriate platforms (Linux for epoll, macOS for kqueue, Windows for IOCP)

Expand networking examples with error handling and graceful shutdown patterns

The examples/ directory only contains basic tcp_server.rs, tcp_listenfd_server.rs, and udp_server.rs. These are minimal implementations that don't demonstrate production patterns like connection limits, timeout handling, or proper resource cleanup. New contributors often learn by example, so comprehensive examples would reduce support burden and improve adoption.

• [ ] Create examples/tcp_server_with_timeout.rs demonstrating read/write timeout handling using mio's event-driven model
• [ ] Create examples/tcp_server_connection_pool.rs showing connection limit management and graceful client disconnection
• [ ] Create examples/multi_protocol_server.rs combining TCP and UDP with event demultiplexing in a single Poll loop
• [ ] Document patterns for handling EWOULDBLOCK and other edge cases specific to non-blocking I/O

Add feature-gated documentation and examples for os-ext feature in src/sys/unix/

The Cargo.toml defines an 'os-ext' feature that enables platform-specific extensions (Unix pipes, Windows security APIs) but src/sys/unix/pipe.rs appears to have no corresponding documentation or examples. New contributors cannot discover or understand when to use these platform-specific APIs. This creates a documentation gap for a significant feature.

• [ ] Create src/sys/unix/pipe.rs module documentation with examples showing proper usage of pipe(2) wrapping
• [ ] Add a examples/unix_pipe_server.rs demonstrating bidirectional pipe communication within the os-ext feature gate
• [ ] Document in src/lib.rs the os-ext feature with specific use cases (e.g., inter-process communication, Unix domain sockets paired with pipes)
• [ ] Ensure all os-ext dependent code in src/sys/windows/ has parallel documentation for feature parity

• Add comprehensive tests for src/sys/unix/selector/poll.rs (poll(2) fallback implementation) — currently no dedicated test files visible, only system-wide integration tests. This ensures the fallback path works on systems without epoll/kqueue.: poll(2) selector is critical for portability but under-tested; good task to understand selector architecture without OS-specific complexity
• Document the Interest bitflags enum and Token type in inline code comments and add examples to src/interest.rs — currently sparse documentation compared to other core types. Add concrete examples showing READABLE | WRITABLE combinations.: These are fundamental to the public API but hard to understand; improving docs reduces barrier to new users
• Implement missing example examples/unix_domain_socket_server.rs following the pattern of tcp_server.rs and udp_server.rs — UDS types exist in src/net/uds/ but no example demonstrates their usage.: UDS is a key feature on Unix but undemonstrated; good task to learn networking primitives and build confidence

Mio is a well-maintained, low-level I/O library with a relatively strong security posture. The codebase follows Rust best practices and avoids common injection vulnerabilities due to its nature as a systems library. Primary concerns are dependency management (libc and windows-sys versions should be kept current), the incomplete Cargo.toml declaration, and the need for better security documentation regarding safe usage of low-level I/O operations. No hardcoded credentials, secrets, or obvious misconfigurations were identified. The library's focus on memory safety through Rust's type system mitigates many traditional C/C++ I/O library vulnerabilities.

• Medium · Outdated libc dependency — Cargo.toml - [target.'cfg(any(unix, target_os = "hermit", target_os = "wasi"))'.dependencies]. The libc dependency is pinned to version 0.2.183, which may contain known vulnerabilities. Regular updates should be applied to receive security patches for the C library bindings. Fix: Regularly update libc to the latest stable version and monitor security advisories. Consider using a more flexible version constraint like '0.2' to allow patch updates while maintaining compatibility.
• Medium · Windows-sys dependency requires security monitoring — Cargo.toml - [target.'cfg(windows)'.dependencies.windows-sys]. The windows-sys dependency (v0.61) includes multiple low-level Windows API bindings (WDK, Win32 APIs). These features provide access to system-level I/O operations that could be misused if not properly validated by callers. Fix: Ensure thorough validation of all parameters passed to Windows API calls. Document unsafe behaviors clearly. Maintain windows-sys at the latest version to receive security patches.
• Low · Incomplete dependency declaration in Cargo.toml — Cargo.toml - end of file. The Cargo.toml file appears truncated with an incomplete target dependency section: '[target.'cfg(target_os = "wasi")'.depen' - this could indicate a malformed or incomplete configuration. Fix: Complete and validate the Cargo.toml file to ensure all dependency declarations are properly formatted and complete.
• Low · Limited security documentation — README.md, src/lib.rs. The README and visible documentation do not explicitly address security considerations for the low-level I/O operations provided by this library. Unsafe I/O operations and platform-specific behavior should be well-documented. Fix: Add a 'Security Considerations' section to the README documenting potential risks when using low-level I/O APIs, particularly around unsafe code usage and platform-specific quirks.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.