1 /// Associates readiness events with [`event::Source`]s.
2 ///
3 /// `Token` is a wrapper around `usize` and is used as an argument to
4 /// [`Registry::register`] and [`Registry::reregister`].
5 ///
6 /// See [`Poll`] for more documentation on polling.
7 ///
8 /// [`event::Source`]: ./event/trait.Source.html
9 /// [`Poll`]: struct.Poll.html
10 /// [`Registry::register`]: struct.Registry.html#method.register
11 /// [`Registry::reregister`]: struct.Registry.html#method.reregister
12 ///
13 /// # Example
14 ///
15 /// Using `Token` to track which socket generated the event. In this example,
16 /// `HashMap` is used, but usually something like [`slab`] is better.
17 ///
18 /// [`slab`]: https://crates.io/crates/slab
19 ///
20 #[cfg_attr(all(feature = "os-poll", features = "net"), doc = "```")]
21 #[cfg_attr(not(all(feature = "os-poll", features = "net")), doc = "```ignore")]
22 /// # use std::error::Error;
23 /// # fn main() -> Result<(), Box<dyn Error>> {
24 /// use mio::{Events, Interest, Poll, Token};
25 /// use mio::net::TcpListener;
26 ///
27 /// use std::thread;
28 /// use std::io::{self, Read};
29 /// use std::collections::HashMap;
30 ///
31 /// // After this number of sockets is accepted, the server will shutdown.
32 /// const MAX_SOCKETS: usize = 32;
33 ///
34 /// // Pick a token that will not be used by any other socket and use that one
35 /// // for the listener.
36 /// const LISTENER: Token = Token(1024);
37 ///
38 /// // Used to store the sockets.
39 /// let mut sockets = HashMap::new();
40 ///
41 /// // This is used to generate a unique token for a socket
42 /// let mut next_socket_index = 0;
43 ///
44 /// // The `Poll` instance
45 /// let mut poll = Poll::new()?;
46 ///
47 /// // Tcp listener
48 /// let mut listener = TcpListener::bind("127.0.0.1:0".parse()?)?;
49 ///
50 /// // Register the listener
51 /// poll.registry().register(&mut listener, LISTENER, Interest::READABLE)?;
52 ///
53 /// // Spawn a thread that will connect a bunch of sockets then close them
54 /// let addr = listener.local_addr()?;
55 /// thread::spawn(move || {
56 ///     use std::net::TcpStream;
57 ///
58 ///     // +1 here is to connect an extra socket to signal the socket to close
59 ///     for _ in 0..(MAX_SOCKETS+1) {
60 ///         // Connect then drop the socket
61 ///         let _ = TcpStream::connect(addr).unwrap();
62 ///     }
63 /// });
64 ///
65 /// // Event storage
66 /// let mut events = Events::with_capacity(1024);
67 ///
68 /// // Read buffer, this will never actually get filled
69 /// let mut buf = [0; 256];
70 ///
71 /// // The main event loop
72 /// loop {
73 ///     // Wait for events
74 ///     poll.poll(&mut events, None)?;
75 ///
76 ///     for event in &events {
77 ///         match event.token() {
78 ///             LISTENER => {
79 ///                 // Perform operations in a loop until `WouldBlock` is
80 ///                 // encountered.
81 ///                 loop {
82 ///                     match listener.accept() {
83 ///                         Ok((mut socket, _)) => {
84 ///                             // Shutdown the server
85 ///                             if next_socket_index == MAX_SOCKETS {
86 ///                                 return Ok(());
87 ///                             }
88 ///
89 ///                             // Get the token for the socket
90 ///                             let token = Token(next_socket_index);
91 ///                             next_socket_index += 1;
92 ///
93 ///                             // Register the new socket w/ poll
94 ///                             poll.registry().register(&mut socket, token, Interest::READABLE)?;
95 ///
96 ///                             // Store the socket
97 ///                             sockets.insert(token, socket);
98 ///                         }
99 ///                         Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
100 ///                             // Socket is not ready anymore, stop accepting
101 ///                             break;
102 ///                         }
103 ///                         e => panic!("err={:?}", e), // Unexpected error
104 ///                     }
105 ///                 }
106 ///             }
107 ///             token => {
108 ///                 // Always operate in a loop
109 ///                 loop {
110 ///                     match sockets.get_mut(&token).unwrap().read(&mut buf) {
111 ///                         Ok(0) => {
112 ///                             // Socket is closed, remove it from the map
113 ///                             sockets.remove(&token);
114 ///                             break;
115 ///                         }
116 ///                         // Data is not actually sent in this example
117 ///                         Ok(_) => unreachable!(),
118 ///                         Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
119 ///                             // Socket is not ready anymore, stop reading
120 ///                             break;
121 ///                         }
122 ///                         e => panic!("err={:?}", e), // Unexpected error
123 ///                     }
124 ///                 }
125 ///             }
126 ///         }
127 ///     }
128 /// }
129 /// # }
130 /// ```
131 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
132 pub struct Token(pub usize);
133 
134 impl From<Token> for usize {
from(val: Token) -> usize135     fn from(val: Token) -> usize {
136         val.0
137     }
138 }
139