feat: EventFd type (#1945)

Author: JonathanWoollett-Light

changelog/1945.added.md

@@ -0,0 +1 @@
+Added `EventFd` type.

changelog/1945.changed.md

@@ -0,0 +1 @@
+Deprecated `sys::eventfd::eventfd`.

src/sys/epoll.rs

@@ -72,7 +72,7 @@ impl EpollEvent {
 
 /// A safe wrapper around [`epoll`](https://man7.org/linux/man-pages/man7/epoll.7.html).
 /// ```
-/// # use nix::sys::{epoll::{EpollTimeout, Epoll, EpollEvent, EpollFlags, EpollCreateFlags}, eventfd::{eventfd, EfdFlags}};
+/// # use nix::sys::{epoll::{EpollTimeout, Epoll, EpollEvent, EpollFlags, EpollCreateFlags}, eventfd::{EventFd, EfdFlags}};
 /// # use nix::unistd::write;
 /// # use std::os::unix::io::{OwnedFd, FromRawFd, AsFd};
 /// # use std::time::{Instant, Duration};
@@ -84,11 +84,11 @@ impl EpollEvent {
 /// let epoll = Epoll::new(EpollCreateFlags::empty())?;
 ///
 /// // Create eventfd & Add event
-/// let eventfd = eventfd(0, EfdFlags::empty())?;
+/// let eventfd = EventFd::new()?;
 /// epoll.add(&eventfd, EpollEvent::new(EpollFlags::EPOLLIN,DATA))?;
 ///
 /// // Arm eventfd & Time wait
-/// write(&eventfd, &1u64.to_ne_bytes())?;
+/// eventfd.arm()?;
 /// let now = Instant::now();
 ///
 /// // Wait on event

src/sys/eventfd.rs

@@ -1,6 +1,6 @@
 use crate::errno::Errno;
-use crate::Result;
-use std::os::unix::io::{FromRawFd, OwnedFd};
+use crate::{Result,unistd};
+use std::os::unix::io::{FromRawFd, OwnedFd, AsRawFd, AsFd, RawFd, BorrowedFd};
 
 libc_bitflags! {
     pub struct EfdFlags: libc::c_int {
@@ -10,8 +10,75 @@ libc_bitflags! {
     }
 }
 
+#[deprecated(since = "0.28.0", note = "Use EventFd::from_value_and_flags() instead")]
 pub fn eventfd(initval: libc::c_uint, flags: EfdFlags) -> Result<OwnedFd> {
     let res = unsafe { libc::eventfd(initval, flags.bits()) };
 
     Errno::result(res).map(|r| unsafe { OwnedFd::from_raw_fd(r) })
 }
+
+#[derive(Debug)]
+#[repr(transparent)]
+pub struct EventFd(OwnedFd);
+impl EventFd {
+    /// [`EventFd::from_value_and_flags`] with `init_val = 0` and `flags = EfdFlags::empty()`.
+    pub fn new() -> Result<Self> {
+        Self::from_value_and_flags(0, EfdFlags::empty())
+    }
+    /// Constructs [`EventFd`] with the given `init_val` and `flags`.
+    /// 
+    /// Wrapper around [`libc::eventfd`].
+    pub fn from_value_and_flags(init_val: u32, flags: EfdFlags) -> Result<Self> {
+        let res = unsafe { libc::eventfd(init_val, flags.bits()) };
+        Errno::result(res).map(|r| Self(unsafe { OwnedFd::from_raw_fd(r) }))
+    }
+    /// [`EventFd::from_value_and_flags`] with `init_val = 0` and given `flags`.
+    pub fn from_flags(flags: EfdFlags) -> Result<Self> {
+        Self::from_value_and_flags(0, flags)
+    }
+    /// [`EventFd::from_value_and_flags`] with given `init_val` and `flags = EfdFlags::empty()`.
+    pub fn from_value(init_val: u32) -> Result<Self> {
+        Self::from_value_and_flags(init_val, EfdFlags::empty())
+    }
+    /// Arms `self`, a following call to `poll`, `select` or `epoll` will return immediately.
+    /// 
+    /// [`EventFd::write`] with `1`.
+    pub fn arm(&self) -> Result<usize> {
+        self.write(1)
+    }
+    /// Defuses `self`, a following call to `poll`, `select` or `epoll` will block.
+    /// 
+    /// [`EventFd::write`] with `0`.
+    pub fn defuse(&self) -> Result<usize> {
+        self.write(0)
+    }
+    /// Enqueues `value` triggers.
+    /// 
+    /// The next `value` calls to `poll`, `select` or `epoll` will return immediately.
+    /// 
+    /// [`EventFd::write`] with `value`.
+    pub fn write(&self, value: u64) -> Result<usize> { 
+        unistd::write(&self.0,&value.to_ne_bytes())
+    }
+    // Reads the value from the file descriptor.
+    pub fn read(&self) -> Result<u64> {
+        let mut arr = [0; std::mem::size_of::<u64>()];
+        unistd::read(self.0.as_raw_fd(),&mut arr)?;
+        Ok(u64::from_ne_bytes(arr))
+    }
+}
+impl AsFd for EventFd {
+    fn as_fd(&self) -> BorrowedFd {
+        self.0.as_fd()
+    }
+}
+impl AsRawFd for EventFd {
+    fn as_raw_fd(&self) -> RawFd {
+        self.0.as_raw_fd()
+    }
+}
+impl From<EventFd> for OwnedFd {
+    fn from(x: EventFd) -> OwnedFd {
+        x.0
+    }
+}