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