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 | /// ``` |
92 | 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 | /// ``` |
106 | 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 | /// ``` |
120 | 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 | /// ``` |
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 | /// ``` |
184 | pub fn clear(&mut self) { |
185 | self.inner.clear(); |
186 | } |
187 | |
188 | /// Returns the inner `sys::Events`. |
189 | 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 | |
198 | 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 | |
206 | fn next(&mut self) -> Option<Self::Item> { |
207 | let ret: Option<&Event> = self |
208 | .inner |
209 | .inner |
210 | .get(self.pos) |
211 | .map(Event::from_sys_event_ref); |
212 | self.pos += 1; |
213 | ret |
214 | } |
215 | |
216 | fn size_hint(&self) -> (usize, Option<usize>) { |
217 | let size: usize = self.inner.inner.len(); |
218 | (size, Some(size)) |
219 | } |
220 | |
221 | fn count(self) -> usize { |
222 | self.inner.inner.len() |
223 | } |
224 | } |
225 | |
226 | impl fmt::Debug for Events { |
227 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
228 | f.debug_list().entries(self).finish() |
229 | } |
230 | } |
231 | |