1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
#![doc(html_root_url = "https://docs.rs/mio/0.7.0-alpha.1")] #![deny(missing_docs, missing_debug_implementations, rust_2018_idioms)] #![cfg_attr(docsrs, feature(doc_cfg))] // Disallow warnings when running tests. #![cfg_attr(test, deny(warnings))] // Disallow warnings in examples. #![doc(test(attr(deny(warnings))))] //! Mio is a fast, low-level I/O library for Rust focusing on non-blocking APIs //! and event notification for building high performance I/O apps with as little //! overhead as possible over the OS abstractions. //! //! # Usage //! //! Using Mio starts by creating a [`Poll`], which reads events from the OS and //! puts them into [`Events`]. You can handle I/O events from the OS with it. //! //! For more detail, see [`Poll`]. //! //! [`Poll`]: ../mio/struct.Poll.html //! [`Events`]: ../mio/event/struct.Events.html //! //! ## Examples //! //! Examples can found in the `examples` directory of the source code, or [on //! GitHub]. //! //! [on GitHub]: https://github.com/tokio-rs/mio/tree/master/examples //! //! ## Guide //! //! A getting started guide is available in the #![cfg_attr(feature = "guide", doc = "[`guide`](../mio/guide/index.html) module.")] #![cfg_attr( not(feature = "guide"), doc = "`guide` (only available when the `guide` feature is enabled)." )] // macros used internally #[macro_use] mod macros; mod interest; mod poll; mod sys; mod token; mod waker; pub mod event; cfg_net! { pub mod net; } #[doc(no_inline)] pub use event::Events; pub use interest::Interest; pub use poll::{Poll, Registry}; pub use token::Token; pub use waker::Waker; #[cfg(unix)] cfg_any_os_util! { pub mod unix { //! Unix only extensions. pub use crate::sys::SourceFd; } } // Enable with `cargo doc --features guide`. #[cfg(feature = "guide")] pub mod guide { //! # Getting started guide. //! //! Using Mio starts by creating a [`Poll`] instance, which reads events from //! the OS and puts them into [`Events`]. //! //! [`Poll`]: ../struct.Poll.html //! [`Events`]: ../event/struct.Events.html //! //! ``` //! # use mio::{Poll, Events}; //! # fn main() -> std::io::Result<()> { //! // `Poll` allows for polling of readiness events. //! let poll = Poll::new()?; //! // `Events` is collection of readiness `Event`s and can be filled by calling //! // `Poll::poll`. //! let events = Events::with_capacity(128); //! # drop((poll, events)); //! # Ok(()) //! # } //! ``` //! //! Next an [event source] needs to be registered with [`Poll`] to receive //! events for it. We'll use a [`TcpListener`] for which we'll receive an event //! once a connection is ready to be accepted. //! //! [event source]: ../event/trait.Source.html //! [`TcpListener`]: ../net/struct.TcpListener.html //! //! ``` //! # use mio::net::TcpListener; //! # use mio::{Poll, Token, Interest}; //! # fn main() -> std::io::Result<()> { //! # let poll = Poll::new()?; //! # let address = "127.0.0.1:0".parse().unwrap(); //! // Create a `TcpListener`, binding it to `address`. //! let mut listener = TcpListener::bind(address)?; //! //! // Next we register it with `Poll` to receive events for it. The `SERVER` //! // `Token` is used to determine that we received an event for the listener //! // later on. //! const SERVER: Token = Token(0); //! poll.registry().register(&mut listener, SERVER, Interest::READABLE)?; //! # Ok(()) //! # } //! ``` //! //! As the name “event source” suggests it is a source of events which can //! be polled using a `Poll` instance. Multiple event sources can be //! [registered] with `Poll`. After we've done this we can start polling //! these events. If we do this in a loop we've got ourselves an event loop. //! //! [registered]: ../struct.Registry.html#method.html //! //! ``` //! # use std::io; //! # use std::time::Duration; //! # use mio::net::TcpListener; //! # use mio::{Poll, Token, Interest, Events}; //! # fn main() -> io::Result<()> { //! # let mut poll = Poll::new()?; //! # let mut events = Events::with_capacity(128); //! # let address = "127.0.0.1:0".parse().unwrap(); //! # let mut listener = TcpListener::bind(address)?; //! # const SERVER: Token = Token(0); //! # poll.registry().register(&mut listener, SERVER, Interest::READABLE)?; //! // Start our event loop. //! loop { //! // Poll Mio for events, waiting at most 100 milliseconds. //! poll.poll(&mut events, Some(Duration::from_millis(100)))?; //! //! // Process each event. //! for event in events.iter() { //! // We can use the token we previously provided to `register` to //! // determine for which type the event is. //! match event.token() { //! SERVER => loop { //! // One or more connections are ready, so we'll attempt to //! // accept them in a loop. //! match listener.accept() { //! Ok((connection, address)) => { //! println!("Got a connection from: {}", address); //! # drop(connection); //! }, //! // A "would block error" is returned if the operation //! // is not ready, so we'll stop trying to accept //! // connections. //! Err(ref err) if would_block(err) => break, //! Err(err) => return Err(err), //! } //! } //! # _ => unreachable!(), //! } //! } //! # return Ok(()); //! } //! //! fn would_block(err: &io::Error) -> bool { //! err.kind() == io::ErrorKind::WouldBlock //! } //! # } //! ``` }