use crate::{sys, Token}; use std::fmt; /// A readiness event. /// /// `Event` is a readiness state paired with a [`Token`]. It is returned by /// [`Poll::poll`]. /// /// For more documentation on polling and events, see [`Poll`]. /// /// [`Poll::poll`]: ../struct.Poll.html#method.poll /// [`Poll`]: ../struct.Poll.html /// [`Token`]: ../struct.Token.html #[derive(Clone)] #[repr(transparent)] pub struct Event { inner: sys::Event, } impl Event { /// Returns the event's token. pub fn token(&self) -> Token { sys::event::token(&self.inner) } /// Returns true if the event contains readable readiness. /// /// # Notes /// /// Out-of-band (OOB) data also triggers readable events. But must /// application don't actually read OOB data, this could leave an /// application open to a Denial-of-Service (Dos) attack, see /// . /// However because Mio uses edge-triggers it will not result in an infinite /// loop as described in the article above. pub fn is_readable(&self) -> bool { sys::event::is_readable(&self.inner) } /// Returns true if the event contains writable readiness. pub fn is_writable(&self) -> bool { sys::event::is_writable(&self.inner) } /// Returns true if the event contains error readiness. /// /// Error events occur when the socket enters an error state. In this case, /// the socket will also receive a readable or writable event. Reading or /// writing to the socket will result in an error. /// /// # Notes /// /// Method is available on all platforms, but not all platforms trigger the /// error event. /// /// The table below shows what flags are checked on what OS. /// /// | [OS selector] | Flag(s) checked | /// |---------------|-----------------| /// | [epoll] | `EPOLLERR` | /// | [kqueue] | `EV_ERROR` and `EV_EOF` with `fflags` set to `0`. | /// /// [OS selector]: ../struct.Poll.html#implementation-notes /// [epoll]: https://man7.org/linux/man-pages/man7/epoll.7.html /// [kqueue]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 pub fn is_error(&self) -> bool { sys::event::is_error(&self.inner) } /// Returns true if the event contains read closed readiness. /// /// # Notes /// /// Read closed readiness can be expected after any of the following have /// occurred: /// * The local stream has shutdown the read half of its socket /// * The local stream has shutdown both the read half and the write half /// of its socket /// * The peer stream has shutdown the write half its socket; this sends a /// `FIN` packet that has been received by the local stream /// /// Method is a best effort implementation. While some platforms may not /// return readiness when read half is closed, it is guaranteed that /// false-positives will not occur. /// /// The table below shows what flags are checked on what OS. /// /// | [OS selector] | Flag(s) checked | /// |---------------|-----------------| /// | [epoll] | `EPOLLHUP`, or | /// | | `EPOLLIN` and `EPOLLRDHUP` | /// | [kqueue] | `EV_EOF` | /// /// [OS selector]: ../struct.Poll.html#implementation-notes /// [epoll]: https://man7.org/linux/man-pages/man7/epoll.7.html /// [kqueue]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 pub fn is_read_closed(&self) -> bool { sys::event::is_read_closed(&self.inner) } /// Returns true if the event contains write closed readiness. /// /// # Notes /// /// On [epoll] this is essentially a check for `EPOLLHUP` flag as the /// local stream shutting down its write half does not trigger this event. /// /// On [kqueue] the local stream shutting down the write half of its /// socket will trigger this event. /// /// Method is a best effort implementation. While some platforms may not /// return readiness when write half is closed, it is guaranteed that /// false-positives will not occur. /// /// The table below shows what flags are checked on what OS. /// /// | [OS selector] | Flag(s) checked | /// |---------------|-----------------| /// | [epoll] | `EPOLLHUP`, or | /// | | only `EPOLLERR`, or | /// | | `EPOLLOUT` and `EPOLLERR` | /// | [kqueue] | `EV_EOF` | /// /// [OS selector]: ../struct.Poll.html#implementation-notes /// [epoll]: https://man7.org/linux/man-pages/man7/epoll.7.html /// [kqueue]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 pub fn is_write_closed(&self) -> bool { sys::event::is_write_closed(&self.inner) } /// Returns true if the event contains priority readiness. /// /// # Notes /// /// Method is available on all platforms, but not all platforms trigger the /// priority event. /// /// The table below shows what flags are checked on what OS. /// /// | [OS selector] | Flag(s) checked | /// |---------------|-----------------| /// | [epoll] | `EPOLLPRI` | /// | [kqueue] | *Not supported* | /// /// [OS selector]: ../struct.Poll.html#implementation-notes /// [epoll]: https://man7.org/linux/man-pages/man7/epoll.7.html /// [kqueue]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 #[inline] pub fn is_priority(&self) -> bool { sys::event::is_priority(&self.inner) } /// Returns true if the event contains AIO readiness. /// /// # Notes /// /// Method is available on all platforms, but not all platforms support AIO. /// /// The table below shows what flags are checked on what OS. /// /// | [OS selector] | Flag(s) checked | /// |---------------|-----------------| /// | [epoll] | *Not supported* | /// | [kqueue]1 | `EVFILT_AIO` | /// /// 1: Only supported on DragonFly BSD, FreeBSD, iOS and macOS. /// /// [OS selector]: ../struct.Poll.html#implementation-notes /// [epoll]: https://man7.org/linux/man-pages/man7/epoll.7.html /// [kqueue]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 pub fn is_aio(&self) -> bool { sys::event::is_aio(&self.inner) } /// Returns true if the event contains LIO readiness. /// /// # Notes /// /// Method is available on all platforms, but only FreeBSD supports LIO. On /// FreeBSD this method checks the `EVFILT_LIO` flag. pub fn is_lio(&self) -> bool { sys::event::is_lio(&self.inner) } /// Create a reference to an `Event` from a platform specific event. pub(crate) fn from_sys_event_ref(sys_event: &sys::Event) -> &Event { unsafe { // This is safe because the memory layout of `Event` is // the same as `sys::Event` due to the `repr(transparent)` attribute. &*(sys_event as *const sys::Event as *const Event) } } } /// When the [alternate] flag is enabled this will print platform specific /// details, for example the fields of the `kevent` structure on platforms that /// use `kqueue(2)`. Note however that the output of this implementation is /// **not** consider a part of the stable API. /// /// [alternate]: fmt::Formatter::alternate impl fmt::Debug for Event { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { let alternate = f.alternate(); let mut d = f.debug_struct("Event"); d.field("token", &self.token()) .field("readable", &self.is_readable()) .field("writable", &self.is_writable()) .field("error", &self.is_error()) .field("read_closed", &self.is_read_closed()) .field("write_closed", &self.is_write_closed()) .field("priority", &self.is_priority()) .field("aio", &self.is_aio()) .field("lio", &self.is_lio()); if alternate { struct EventDetails<'a>(&'a sys::Event); impl<'a> fmt::Debug for EventDetails<'a> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { sys::event::debug_details(f, self.0) } } d.field("details", &EventDetails(&self.inner)).finish() } else { d.finish() } } }