1use crate::event::Event;
2use crate::sys;
3
4use 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/// ```
42pub 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)]
76pub struct Iter<'a> {
77 inner: &'a Events,
78 pos: usize,
79}
80
81impl 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
194impl<'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
203impl<'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
226impl fmt::Debug for Events {
227 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
228 f.debug_list().entries(self).finish()
229 }
230}
231