1# Mio – Metal I/O
2
3Mio is a fast, low-level I/O library for Rust focusing on non-blocking APIs and
4event notification for building high performance I/O apps with as little
5overhead as possible over the OS abstractions.
6
7[![Crates.io][crates-badge]][crates-url]
8[![MIT licensed][mit-badge]][mit-url]
9[![Build Status][actions-badge]][actions-url]
10[![Build Status][cirrus-badge]][cirrus-url]
11
12[crates-badge]: https://img.shields.io/crates/v/mio.svg
13[crates-url]: https://crates.io/crates/mio
14[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
15[mit-url]: LICENSE
16[actions-badge]: https://github.com/tokio-rs/mio/workflows/CI/badge.svg
17[actions-url]: https://github.com/tokio-rs/mio/actions?query=workflow%3ACI+branch%3Amaster
18[cirrus-badge]: https://api.cirrus-ci.com/github/tokio-rs/mio.svg
19[cirrus-url]: https://cirrus-ci.com/github/tokio-rs/mio
20
21**API documentation**
22
23* [v1](https://docs.rs/mio/^1)
24* [v0.8](https://docs.rs/mio/^0.8)
25
26This is a low level library, if you are looking for something easier to get
27started with, see [Tokio](https://tokio.rs).
28
29## Usage
30
31To use `mio`, first add this to your `Cargo.toml`:
32
33```toml
34[dependencies]
35mio = "1"
36```
37
38Next we can start using Mio. The following is quick introduction using
39`TcpListener` and `TcpStream`. Note that `features = ["os-poll", "net"]` must be
40specified for this example.
41
42```rust
43use std::error::Error;
44
45use mio::net::{TcpListener, TcpStream};
46use mio::{Events, Interest, Poll, Token};
47
48// Some tokens to allow us to identify which event is for which socket.
49const SERVER: Token = Token(0);
50const CLIENT: Token = Token(1);
51
52fn main() -> Result<(), Box<dyn Error>> {
53    // Create a poll instance.
54    let mut poll = Poll::new()?;
55    // Create storage for events.
56    let mut events = Events::with_capacity(128);
57
58    // Setup the server socket.
59    let addr = "127.0.0.1:13265".parse()?;
60    let mut server = TcpListener::bind(addr)?;
61    // Start listening for incoming connections.
62    poll.registry()
63        .register(&mut server, SERVER, Interest::READABLE)?;
64
65    // Setup the client socket.
66    let mut client = TcpStream::connect(addr)?;
67    // Register the socket.
68    poll.registry()
69        .register(&mut client, CLIENT, Interest::READABLE | Interest::WRITABLE)?;
70
71    // Start an event loop.
72    loop {
73        // Poll Mio for events, blocking until we get an event.
74        poll.poll(&mut events, None)?;
75
76        // Process each event.
77        for event in events.iter() {
78            // We can use the token we previously provided to `register` to
79            // determine for which socket the event is.
80            match event.token() {
81                SERVER => {
82                    // If this is an event for the server, it means a connection
83                    // is ready to be accepted.
84                    //
85                    // Accept the connection and drop it immediately. This will
86                    // close the socket and notify the client of the EOF.
87                    let connection = server.accept();
88                    drop(connection);
89                }
90                CLIENT => {
91                    if event.is_writable() {
92                        // We can (likely) write to the socket without blocking.
93                    }
94
95                    if event.is_readable() {
96                        // We can (likely) read from the socket without blocking.
97                    }
98
99                    // Since the server just shuts down the connection, let's
100                    // just exit from our event loop.
101                    return Ok(());
102                }
103                // We don't expect any events with tokens other than those we provided.
104                _ => unreachable!(),
105            }
106        }
107    }
108}
109```
110
111## Features
112
113* Non-blocking TCP, UDP, UDS
114* I/O event queue backed by epoll, kqueue, and IOCP
115* Zero allocations at runtime
116* Platform specific extensions
117
118## Non-goals
119
120The following are specifically omitted from Mio and are left to the user
121or higher-level libraries.
122
123* File operations
124* Thread pools / multi-threaded event loop
125* Timers
126
127## Platforms
128
129Currently supported platforms:
130
131* Android (API level 21)
132* DragonFly BSD
133* FreeBSD
134* Linux
135* NetBSD
136* OpenBSD
137* Windows
138* iOS
139* macOS
140
141Mio can handle interfacing with each of the event systems of the aforementioned
142platforms. The details of their implementation are further discussed in the
143`Poll` type of the API documentation (see above).
144
145Mio generally supports the same versions of the above mentioned platforms as
146Rust the language (rustc) does, unless otherwise noted.
147
148The Windows implementation for polling sockets is using the [wepoll] strategy.
149This uses the Windows AFD system to access socket readiness events.
150
151[wepoll]: https://github.com/piscisaureus/wepoll
152
153### Unsupported
154
155* Wine, see [issue #1444]
156
157[issue #1444]: https://github.com/tokio-rs/mio/issues/1444
158
159## MSRV Policy
160
161The MSRV (Minimum Supported Rust Version) is fixed for a given minor (1.x)
162version. However it can be increased when bumping minor versions, i.e. going
163from 1.0 to 1.1 allows us to increase the MSRV. Users unable to increase their
164Rust version can use an older minor version instead. Below is a list of Mio versions
165and their MSRV:
166
167 * v0.8: Rust 1.46.
168 * v1.0: Rust 1.70.
169
170Note however that Mio also has dependencies, which might have different MSRV
171policies. We try to stick to the above policy when updating dependencies, but
172this is not always possible.
173
174## Unsupported flags
175
176Mio uses different implementations to support the same functionality depending
177on the platform. Mio generally uses the "best" implementation possible, where
178"best" usually means most efficient for Mio's use case. However this means that
179the implementation is often specific to a limited number of platforms, meaning
180we often have multiple implementations for the same functionality. In some cases
181it might be required to not use the "best" implementation, but another
182implementation Mio supports (on other platforms). **Mio does not officially
183support secondary implementations on platforms**, however we do have various cfg
184flags to force another implementation for these situations.
185
186Current flags:
187 * `mio_unsupported_force_poll_poll`, uses an implementation based on `poll(2)`
188   for `mio::Poll`.
189 * `mio_unsupported_force_waker_pipe`, uses an implementation based on `pipe(2)`
190   for `mio::Waker`.
191
192**Again, Mio does not officially supports this**. Furthermore these flags may
193disappear in the future.
194
195## Community
196
197A group of Mio users hang out on [Discord], this can be a good place to go for
198questions. It's also possible to open a [new issue on GitHub] to ask questions,
199report bugs or suggest new features.
200
201[Discord]: https://discord.gg/tokio
202[new issue on GitHub]: https://github.com/tokio-rs/mio/issues/new
203
204## Contributing
205
206Interested in getting involved? We would love to help you! For simple
207bug fixes, just submit a PR with the fix and we can discuss the fix
208directly in the PR. If the fix is more complex, start with an issue.
209
210If you want to propose an API change, create an issue to start a
211discussion with the community. Also, feel free to talk with us in Discord.
212
213Finally, be kind. We support the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct).
214