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