Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 230 insertions, 0 deletions

diff --git a/third_party/rust/mio/src/event/event.rs b/third_party/rust/mio/src/event/event.rs
new file mode 100644
index 0000000000..2d85742b96
--- /dev/null
+++ b/third_party/rust/mio/src/event/event.rs
@@ -0,0 +1,230 @@
+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
+    /// <https://github.com/sandstorm-io/sandstorm-website/blob/58f93346028c0576e8147627667328eaaf4be9fa/_posts/2015-04-08-osx-security-bug.md>.
+    /// 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]<sup>1</sup> | `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()
+        }
+    }
+}