1 use crate::event::Event; 2 use crate::sys; 3 4 use std::fmt; 5 6 /// A collection of readiness events. 7 /// 8 /// `Events` is passed as an argument to [`Poll::poll`] and will be used to 9 /// receive any new readiness events received since the last poll. Usually, a 10 /// single `Events` instance is created at the same time as a [`Poll`] and 11 /// reused on each call to [`Poll::poll`]. 12 /// 13 /// See [`Poll`] for more documentation on polling. 14 /// 15 /// [`Poll::poll`]: ../struct.Poll.html#method.poll 16 /// [`Poll`]: ../struct.Poll.html 17 /// 18 /// # Examples 19 /// 20 #[cfg_attr(feature = "os-poll", doc = "```")] 21 #[cfg_attr(not(feature = "os-poll"), doc = "```ignore")] 22 /// # use std::error::Error; 23 /// # fn main() -> Result<(), Box<dyn Error>> { 24 /// use mio::{Events, Poll}; 25 /// use std::time::Duration; 26 /// 27 /// let mut events = Events::with_capacity(1024); 28 /// let mut poll = Poll::new()?; 29 /// # 30 /// # assert!(events.is_empty()); 31 /// 32 /// // Register `event::Source`s with `poll`. 33 /// 34 /// poll.poll(&mut events, Some(Duration::from_millis(100)))?; 35 /// 36 /// for event in events.iter() { 37 /// println!("Got an event for {:?}", event.token()); 38 /// } 39 /// # Ok(()) 40 /// # } 41 /// ``` 42 pub struct Events { 43 inner: sys::Events, 44 } 45 46 /// [`Events`] iterator. 47 /// 48 /// This struct is created by the [`iter`] method on [`Events`]. 49 /// 50 /// [`Events`]: struct.Events.html 51 /// [`iter`]: struct.Events.html#method.iter 52 /// 53 /// # Examples 54 /// 55 #[cfg_attr(feature = "os-poll", doc = "```")] 56 #[cfg_attr(not(feature = "os-poll"), doc = "```ignore")] 57 /// # use std::error::Error; 58 /// # fn main() -> Result<(), Box<dyn Error>> { 59 /// use mio::{Events, Poll}; 60 /// use std::time::Duration; 61 /// 62 /// let mut events = Events::with_capacity(1024); 63 /// let mut poll = Poll::new()?; 64 /// 65 /// // Register handles with `poll`. 66 /// 67 /// poll.poll(&mut events, Some(Duration::from_millis(100)))?; 68 /// 69 /// for event in events.iter() { 70 /// println!("Got an event for {:?}", event.token()); 71 /// } 72 /// # Ok(()) 73 /// # } 74 /// ``` 75 #[derive(Debug, Clone)] 76 pub struct Iter<'a> { 77 inner: &'a Events, 78 pos: usize, 79 } 80 81 impl Events { 82 /// Return a new `Events` capable of holding up to `capacity` events. 83 /// 84 /// # Examples 85 /// 86 /// ``` 87 /// use mio::Events; 88 /// 89 /// let events = Events::with_capacity(1024); 90 /// assert_eq!(1024, events.capacity()); 91 /// ``` with_capacity(capacity: usize) -> Events92 pub fn with_capacity(capacity: usize) -> Events { 93 Events { 94 inner: sys::Events::with_capacity(capacity), 95 } 96 } 97 98 /// Returns the number of `Event` values that `self` can hold. 99 /// 100 /// ``` 101 /// use mio::Events; 102 /// 103 /// let events = Events::with_capacity(1024); 104 /// assert_eq!(1024, events.capacity()); 105 /// ``` capacity(&self) -> usize106 pub fn capacity(&self) -> usize { 107 self.inner.capacity() 108 } 109 110 /// Returns `true` if `self` contains no `Event` values. 111 /// 112 /// # Examples 113 /// 114 /// ``` 115 /// use mio::Events; 116 /// 117 /// let events = Events::with_capacity(1024); 118 /// assert!(events.is_empty()); 119 /// ``` is_empty(&self) -> bool120 pub fn is_empty(&self) -> bool { 121 self.inner.is_empty() 122 } 123 124 /// Returns an iterator over the `Event` values. 125 /// 126 /// # Examples 127 /// 128 #[cfg_attr(feature = "os-poll", doc = "```")] 129 #[cfg_attr(not(feature = "os-poll"), doc = "```ignore")] 130 /// # use std::error::Error; 131 /// # fn main() -> Result<(), Box<dyn Error>> { 132 /// use mio::{Events, Poll}; 133 /// use std::time::Duration; 134 /// 135 /// let mut events = Events::with_capacity(1024); 136 /// let mut poll = Poll::new()?; 137 /// 138 /// // Register handles with `poll`. 139 /// 140 /// poll.poll(&mut events, Some(Duration::from_millis(100)))?; 141 /// 142 /// for event in events.iter() { 143 /// println!("Got an event for {:?}", event.token()); 144 /// } 145 /// # Ok(()) 146 /// # } 147 /// ``` iter(&self) -> Iter<'_>148 pub fn iter(&self) -> Iter<'_> { 149 Iter { 150 inner: self, 151 pos: 0, 152 } 153 } 154 155 /// Clearing all `Event` values from container explicitly. 156 /// 157 /// # Notes 158 /// 159 /// Events are cleared before every `poll`, so it is not required to call 160 /// this manually. 161 /// 162 /// # Examples 163 /// 164 #[cfg_attr(feature = "os-poll", doc = "```")] 165 #[cfg_attr(not(feature = "os-poll"), doc = "```ignore")] 166 /// # use std::error::Error; 167 /// # fn main() -> Result<(), Box<dyn Error>> { 168 /// use mio::{Events, Poll}; 169 /// use std::time::Duration; 170 /// 171 /// let mut events = Events::with_capacity(1024); 172 /// let mut poll = Poll::new()?; 173 /// 174 /// // Register handles with `poll`. 175 /// 176 /// poll.poll(&mut events, Some(Duration::from_millis(100)))?; 177 /// 178 /// // Clear all events. 179 /// events.clear(); 180 /// assert!(events.is_empty()); 181 /// # Ok(()) 182 /// # } 183 /// ``` clear(&mut self)184 pub fn clear(&mut self) { 185 self.inner.clear(); 186 } 187 188 /// Returns the inner `sys::Events`. sys(&mut self) -> &mut sys::Events189 pub(crate) fn sys(&mut self) -> &mut sys::Events { 190 &mut self.inner 191 } 192 } 193 194 impl<'a> IntoIterator for &'a Events { 195 type Item = &'a Event; 196 type IntoIter = Iter<'a>; 197 into_iter(self) -> Self::IntoIter198 fn into_iter(self) -> Self::IntoIter { 199 self.iter() 200 } 201 } 202 203 impl<'a> Iterator for Iter<'a> { 204 type Item = &'a Event; 205 next(&mut self) -> Option<Self::Item>206 fn next(&mut self) -> Option<Self::Item> { 207 let ret = self 208 .inner 209 .inner 210 .get(self.pos) 211 .map(Event::from_sys_event_ref); 212 self.pos += 1; 213 ret 214 } 215 size_hint(&self) -> (usize, Option<usize>)216 fn size_hint(&self) -> (usize, Option<usize>) { 217 let size = self.inner.inner.len(); 218 (size, Some(size)) 219 } 220 count(self) -> usize221 fn count(self) -> usize { 222 self.inner.inner.len() 223 } 224 } 225 226 impl fmt::Debug for Events { fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result227 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 228 f.debug_list().entries(self).finish() 229 } 230 } 231