README.md
1# Mio – Metal IO
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][azure-badge]][azure-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[azure-badge]: https://dev.azure.com/tokio-rs/Tokio/_apis/build/status/tokio-rs.mio?branchName=master
17[azure-url]: https://dev.azure.com/tokio-rs/Tokio/_build/latest?definitionId=2&branchName=master
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* [master](https://tokio-rs.github.io/mio/doc/mio/)
24* [v0.7](https://docs.rs/mio/^0.7)
25* [v0.6](https://docs.rs/mio/^0.6)
26
27This is a low level library, if you are looking for something easier to get
28started with, see [Tokio](https://tokio.rs).
29
30## Usage
31
32To use `mio`, first add this to your `Cargo.toml`:
33
34```toml
35[dependencies]
36mio = "0.7"
37```
38
39Next we can start using Mio. The following is quick introduction using
40`TcpListener` and `TcpStream`. Note that `features = ["os-poll", "net"]` must be
41specified for this example.
42
43```rust
44use std::error::Error;
45
46use mio::net::{TcpListener, TcpStream};
47use mio::{Events, Interest, Poll, Token};
48
49// Some tokens to allow us to identify which event is for which socket.
50const SERVER: Token = Token(0);
51const CLIENT: Token = Token(1);
52
53fn main() -> Result<(), Box<dyn Error>> {
54 // Create a poll instance.
55 let mut poll = Poll::new()?;
56 // Create storage for events.
57 let mut events = Events::with_capacity(128);
58
59 // Setup the server socket.
60 let addr = "127.0.0.1:13265".parse()?;
61 let mut server = TcpListener::bind(addr)?;
62 // Start listening for incoming connections.
63 poll.registry()
64 .register(&mut server, SERVER, Interest::READABLE)?;
65
66 // Setup the client socket.
67 let mut client = TcpStream::connect(addr)?;
68 // Register the socket.
69 poll.registry()
70 .register(&mut client, CLIENT, Interest::READABLE | Interest::WRITABLE)?;
71
72 // Start an event loop.
73 loop {
74 // Poll Mio for events, blocking until we get an event.
75 poll.poll(&mut events, None)?;
76
77 // Process each event.
78 for event in events.iter() {
79 // We can use the token we previously provided to `register` to
80 // determine for which socket the event is.
81 match event.token() {
82 SERVER => {
83 // If this is an event for the server, it means a connection
84 // is ready to be accepted.
85 //
86 // Accept the connection and drop it immediately. This will
87 // close the socket and notify the client of the EOF.
88 let connection = server.accept();
89 drop(connection);
90 }
91 CLIENT => {
92 if event.is_writable() {
93 // We can (likely) write to the socket without blocking.
94 }
95
96 if event.is_readable() {
97 // We can (likely) read from the socket without blocking.
98 }
99
100 // Since the server just shuts down the connection, let's
101 // just exit from our event loop.
102 return Ok(());
103 }
104 // We don't expect any events with tokens other than those we provided.
105 _ => unreachable!(),
106 }
107 }
108 }
109}
110```
111
112## Features
113
114* Non-blocking TCP, UDP
115* I/O event queue backed by epoll, kqueue, and IOCP
116* Zero allocations at runtime
117* Platform specific extensions
118
119## Non-goals
120
121The following are specifically omitted from Mio and are left to the user
122or higher-level libraries.
123
124* File operations
125* Thread pools / multi-threaded event loop
126* Timers
127
128## Platforms
129
130Currently supported platforms:
131
132* Android
133* DragonFly BSD
134* FreeBSD
135* Linux
136* NetBSD
137* OpenBSD
138* Solaris
139* Windows
140* iOS
141* macOS
142
143There are potentially others. If you find that Mio works on another
144platform, submit a PR to update the list!
145
146Mio can handle interfacing with each of the event systems of the aforementioned
147platforms. The details of their implementation are further discussed in the
148`Poll` type of the API documentation (see above).
149
150The Windows implementation for polling sockets is using the [wepoll] strategy.
151This uses the Windows AFD system to access socket readiness events.
152
153[wepoll]: https://github.com/piscisaureus/wepoll
154
155## Community
156
157A group of Mio users hang out on [Discord], this can be a good place to go for
158questions.
159
160[Discord]: https://discord.gg/tokio
161
162## Contributing
163
164Interested in getting involved? We would love to help you! For simple
165bug fixes, just submit a PR with the fix and we can discuss the fix
166directly in the PR. If the fix is more complex, start with an issue.
167
168If you want to propose an API change, create an issue to start a
169discussion with the community. Also, feel free to talk with us in Discord.
170
171Finally, be kind. We support the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct).
172
