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* [v0.8](https://docs.rs/mio/^0.8) 24* [v0.7](https://docs.rs/mio/^0.7) 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.8" 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 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 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### Unsupported 154 155* Haiku, see [issue #1472] 156* Solaris, see [issue #1152] 157* Wine, see [issue #1444] 158 159[issue #1472]: https://github.com/tokio-rs/mio/issues/1472 160[issue #1152]: https://github.com/tokio-rs/mio/issues/1152 161[issue #1444]: https://github.com/tokio-rs/mio/issues/1444 162 163## Community 164 165A group of Mio users hang out on [Discord], this can be a good place to go for 166questions. 167 168[Discord]: https://discord.gg/tokio 169 170## Contributing 171 172Interested in getting involved? We would love to help you! For simple 173bug fixes, just submit a PR with the fix and we can discuss the fix 174directly in the PR. If the fix is more complex, start with an issue. 175 176If you want to propose an API change, create an issue to start a 177discussion with the community. Also, feel free to talk with us in Discord. 178 179Finally, be kind. We support the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct). 180
