corcovado/
lib.rs

1//! A fast, low-level IO library for Rust focusing on non-blocking APIs, event
2//! notification, and other useful utilities for building high performance IO
3//! apps.
4//!
5//! # Features
6//!
7//! * Non-blocking TCP, UDP
8//! * I/O event notification queue backed by epoll, kqueue, and IOCP
9//! * Zero allocations at runtime
10//! * Platform specific extensions
11//!
12//! # Non-goals
13//!
14//! The following are specifically omitted from Mio and are left to the user or higher-level libraries.
15//!
16//! * File operations
17//! * Thread pools / multi-threaded event loop
18//! * Timers
19//!
20//! # Platforms
21//!
22//! Currently supported platforms:
23//!
24//! * Linux
25//! * OS X
26//! * Windows
27//! * FreeBSD
28//! * NetBSD
29//! * Android
30//! * iOS
31//!
32//! mio can handle interfacing with each of the event notification systems of the aforementioned platforms. The details of
33//! their implementation are further discussed in [`Poll`].
34//!
35//! # Usage
36//!
37//! Using mio starts by creating a [`Poll`], which reads events from the OS and
38//! put them into [`Events`]. You can handle IO events from the OS with it.
39//!
40//! For more detail, see [`Poll`].
41//!
42//! [`Poll`]: struct.Poll.html
43//! [`Events`]: struct.Events.html
44//!
45// # Example
46//
47// ```
48// use corcovado::*;
49// use std::net::{TcpListener, TcpStream};
50//
51// // Setup some tokens to allow us to identify which event is
52// // for which socket.
53// const SERVER: Token = Token(0);
54// const CLIENT: Token = Token(1);
55//
56// let addr = "127.0.0.1:13265".parse().unwrap();
57//
58// // Setup the server socket
59// let server = TcpListener::bind(&addr).unwrap();
60//
61// // Create a poll instance
62// let poll = Poll::new().unwrap();
63//
64// // Start listening for incoming connections
65// poll.register(&server, SERVER, Ready::readable(),
66//               PollOpt::edge()).unwrap();
67//
68// // Setup the client socket
69// let sock = TcpStream::connect(&addr).unwrap();
70//
71// // Register the socket
72// poll.register(&sock, CLIENT, Ready::readable(),
73//               PollOpt::edge()).unwrap();
74//
75// // Create storage for events
76// let mut events = Events::with_capacity(1024);
77//
78// loop {
79//     poll.poll(&mut events, None).unwrap();
80//
81//     for event in events.iter() {
82//         match event.token() {
83//             SERVER => {
84//                 // Accept and drop the socket immediately, this will close
85//                 // the socket and notify the client of the EOF.
86//                 let _ = server.accept();
87//             }
88//             CLIENT => {
89//                 // The server just shuts down the socket, let's just exit
90//                 // from our event loop.
91//                 return;
92//             }
93//             _ => unreachable!(),
94//         }
95//     }
96// }
97//
98// ```
99
100extern crate iovec;
101extern crate net2;
102extern crate slab;
103
104#[cfg(target_os = "fuchsia")]
105extern crate fuchsia_zircon as zircon;
106#[cfg(target_os = "fuchsia")]
107extern crate fuchsia_zircon_sys as zircon_sys;
108
109#[cfg(unix)]
110extern crate libc;
111
112#[cfg(windows)]
113extern crate miow;
114
115#[cfg(windows)]
116extern crate windows_sys;
117
118#[macro_use]
119extern crate tracing;
120
121mod event_imp;
122mod io;
123mod lazycell;
124mod poll;
125#[cfg(unix)]
126mod socket;
127mod sys;
128mod token;
129
130pub mod channel;
131#[cfg(unix)]
132pub mod stream;
133pub mod timer;
134
135pub use event_imp::{PollOpt, Ready};
136pub use poll::{Poll, Registration, SetReadiness};
137pub use token::Token;
138
139pub mod event {
140    //! Readiness event types and utilities.
141
142    pub use super::event_imp::{Event, Evented};
143    pub use super::poll::{Events, Iter};
144}
145
146pub use event::Events;
147
148#[cfg(all(unix, not(target_os = "fuchsia")))]
149pub mod unix {
150    //! Unix only extensions
151    pub use sys::unix::UnixReady;
152    pub use sys::EventedFd;
153}
154
155#[cfg(target_os = "fuchsia")]
156pub mod fuchsia {
157    //! Fuchsia-only extensions
158    //!
159    //! # Stability
160    //!
161    //! This module depends on the [magenta-sys crate](https://crates.io/crates/magenta-sys)
162    //! and so might introduce breaking changes, even on minor releases,
163    //! so long as that crate remains unstable.
164    pub use sys::fuchsia::{zx_signals_t, FuchsiaReady};
165    pub use sys::EventedHandle;
166}
167
168/// Windows-only extensions to the mio crate.
169///
170/// Mio on windows is currently implemented with IOCP for a high-performance
171/// implementation of asynchronous I/O. Mio then provides TCP and UDP as sample
172/// bindings for the system to connect networking types to asynchronous I/O. On
173/// Unix this scheme is then also extensible to all other file descriptors with
174/// the `EventedFd` type, but on Windows no such analog is available. The
175/// purpose of this module, however, is to similarly provide a mechanism for
176/// foreign I/O types to get hooked up into the IOCP event loop.
177///
178/// This module provides two types for interfacing with a custom IOCP handle:
179///
180/// * `Binding` - this type is intended to govern binding with mio's `Poll`
181///   type. Each I/O object should contain an instance of `Binding` that's
182///   interfaced with for the implementation of the `Evented` trait. The
183///   `register`, `reregister`, and `deregister` methods for the `Evented` trait
184///   all have rough analogs with `Binding`.
185///
186///   Note that this type **does not handle readiness**. That is, this type does
187///   not handle whether sockets are readable/writable/etc. It's intended that
188///   IOCP types will internally manage this state with a `SetReadiness` type
189///   from the `poll` module. The `SetReadiness` is typically lazily created on
190///   the first time that `Evented::register` is called and then stored in the
191///   I/O object.
192///
193///   Also note that for types which represent streams of bytes the mio
194///   interface of *readiness* doesn't map directly to the Windows model of
195///   *completion*. This means that types will have to perform internal
196///   buffering to ensure that a readiness interface can be provided. For a
197///   sample implementation see the TCP/UDP modules in mio itself.
198///
199/// * `Overlapped` - this type is intended to be used as the concrete instances
200///   of the `OVERLAPPED` type that most win32 methods expect. It's crucial, for
201///   safety, that all asynchronous operations are initiated with an instance of
202///   `Overlapped` and not another instantiation of `OVERLAPPED`.
203///
204///   Mio's `Overlapped` type is created with a function pointer that receives
205///   a `OVERLAPPED_ENTRY` type when called. This `OVERLAPPED_ENTRY` type is
206///   defined in the `winapi` crate. Whenever a completion is posted to an IOCP
207///   object the `OVERLAPPED` that was signaled will be interpreted as
208///   `Overlapped` in the mio crate and this function pointer will be invoked.
209///   Through this function pointer, and through the `OVERLAPPED` pointer,
210///   implementations can handle management of I/O events.
211///
212/// When put together these two types enable custom Windows handles to be
213/// registered with mio's event loops. The `Binding` type is used to associate
214/// handles and the `Overlapped` type is used to execute I/O operations. When
215/// the I/O operations are completed a custom function pointer is called which
216/// typically modifies a `SetReadiness` set by `Evented` methods which will get
217/// later hooked into the mio event loop.
218#[cfg(windows)]
219pub mod windows {
220
221    pub use sys::{Binding, Overlapped};
222}
corcovado/lib.rs

corcovado/
lib.rs
