Epoll type

Author: JonathanWoollett-Light

CHANGELOG.md

@@ -67,6 +67,8 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 - The MSRV is now 1.63.0
   ([#1882](https://github.com/nix-rust/nix/pull/1882))
+- The epoll interface now uses a type.
+  ([#1882](https://github.com/nix-rust/nix/pull/1882))
 - The `addr` argument of `sys::mman::mmap` is now of type `Option<NonZeroUsize>`.
   ([#1870](https://github.com/nix-rust/nix/pull/1870))
 - The `length` argument of `sys::mman::mmap` is now of type `NonZeroUsize`.

src/sys/epoll.rs

@@ -2,8 +2,7 @@ use crate::errno::Errno;
 use crate::Result;
 use libc::{self, c_int};
 use std::mem;
-use std::os::unix::io::RawFd;
-use std::ptr;
+use std::os::unix::io::{FromRawFd,RawFd, OwnedFd, AsFd, AsRawFd};
 
 libc_bitflags!(
     pub struct EpollFlags: c_int {
@@ -70,20 +69,126 @@ impl EpollEvent {
     }
 }
 
+/// A safe wrapper around [`epoll`](https://man7.org/linux/man-pages/man7/epoll.7.html).
+/// ```
+/// # use nix::sys::{epoll::{Epoll, EpollEvent, EpollFlags, EpollCreateFlags}, eventfd::{eventfd, EfdFlags}};
+/// # use nix::unistd::write;
+/// # use std::os::unix::io::{OwnedFd, FromRawFd, AsRawFd, AsFd};
+/// # use std::time::{Instant, Duration};
+/// # fn main() -> nix::Result<()> {
+/// const DATA: u64 = 17;
+/// const MILLIS: u64 = 100;
+/// 
+/// // Create epoll
+/// let epoll = Epoll::new(EpollCreateFlags::empty())?;
+/// 
+/// // Create eventfd & Add event
+/// let eventfd = unsafe { OwnedFd::from_raw_fd(eventfd(0, EfdFlags::empty())?) };
+/// epoll.add(&eventfd, EpollEvent::new(EpollFlags::EPOLLIN,DATA))?;
+/// 
+/// // Arm eventfd & Time wait
+/// write(eventfd.as_raw_fd(), &1u64.to_ne_bytes())?;
+/// let now = Instant::now();
+/// 
+/// // Wait on event
+/// let mut events = [EpollEvent::empty()];
+/// epoll.wait(&mut events, MILLIS as isize)?;
+/// 
+/// // Assert data correct & timeout didn't occur
+/// assert_eq!(events[0].data(), DATA);
+/// assert!(now.elapsed() < Duration::from_millis(MILLIS));
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug)]
+pub struct Epoll(pub OwnedFd);
+impl Epoll {
+    /// Creates a new epoll instance and returns a file descriptor referring to that instance.
+    /// 
+    /// [`epoll_create1`](https://man7.org/linux/man-pages/man2/epoll_create1.2.html).
+    pub fn new(flags: EpollCreateFlags) -> Result<Self> {
+        let res = unsafe { libc::epoll_create1(flags.bits()) };
+        let fd = Errno::result(res)?;
+        let owned_fd = unsafe { OwnedFd::from_raw_fd(fd) };
+        Ok(Self(owned_fd))
+    }
+    /// Add an entry to the interest list of the epoll file descriptor for
+    /// specified in events. 
+    /// 
+    /// [`epoll_ctl`](https://man7.org/linux/man-pages/man2/epoll_ctl.2.html) with `EPOLL_CTL_ADD`.
+    pub fn add<Fd: AsFd>(&self, fd: Fd, mut event: EpollEvent) -> Result<()> {
+        self.epoll_ctl(EpollOp::EpollCtlAdd,fd,&mut event)
+    }
+    /// Remove (deregister) the target file descriptor `fd` from the interest list.
+    /// 
+    /// [`epoll_ctl`](https://man7.org/linux/man-pages/man2/epoll_ctl.2.html) with `EPOLL_CTL_DEL` .
+    pub fn delete<Fd: AsFd>(&self, fd: Fd) -> Result<()> {
+        self.epoll_ctl(EpollOp::EpollCtlDel,fd,None)
+    }
+    /// Change the settings associated with `fd` in the interest list to the new settings specified
+    /// in `event`.
+    /// 
+    /// [`epoll_ctl`](https://man7.org/linux/man-pages/man2/epoll_ctl.2.html) with `EPOLL_CTL_MOD`.
+    pub fn modify<Fd: AsFd>(&self,fd: Fd, event: &mut EpollEvent) -> Result<()> {
+        self.epoll_ctl(EpollOp::EpollCtlMod,fd,event)
+    }
+    /// Waits for I/O events, blocking the calling thread if no events are currently available.
+    /// (This can be thought of as fetching items from the ready list of the epoll instance.)
+    /// 
+    /// [`epoll_wait`](https://man7.org/linux/man-pages/man2/epoll_wait.2.html)
+    pub fn wait(&self, events: &mut [EpollEvent], timeout: isize) -> Result<usize> {
+        let res = unsafe {
+            libc::epoll_wait(
+                self.0.as_raw_fd(),
+                events.as_mut_ptr() as *mut libc::epoll_event,
+                events.len() as c_int,
+                timeout as c_int,
+            )
+        };
+    
+        Errno::result(res).map(|r| r as usize)
+    }
+    /// This system call is used to add, modify, or remove entries in the interest list of the epoll
+    /// instance referred to by `self`. It requests that the operation `op` be performed for the
+    /// target file descriptor, `fd`.
+    /// 
+    /// When possible prefer [`Epoll::add`], [`Epoll::delete`] and [`Epoll::modify`].
+    /// 
+    /// [`epoll_ctl`](https://man7.org/linux/man-pages/man2/epoll_ctl.2.html)
+    fn epoll_ctl<'a, Fd: AsFd, T>(
+        &self,
+        op: EpollOp,
+        fd: Fd,
+        event: T,
+    ) -> Result<()>
+    where
+        T: Into<Option<&'a mut EpollEvent>>,
+    {
+        let event: Option<&mut EpollEvent> = event.into();
+        let ptr = event.map(|x|&mut x.event as *mut libc::epoll_event).unwrap_or(std::ptr::null_mut());
+        unsafe {
+            Errno::result(libc::epoll_ctl(self.0.as_raw_fd(), op as c_int, fd.as_fd().as_raw_fd(), ptr)).map(drop)
+        }
+    }
+}
+
+#[deprecated(since = "0.27.0", note = "Use Epoll::new() instead")]
 #[inline]
 pub fn epoll_create() -> Result<RawFd> {
     let res = unsafe { libc::epoll_create(1024) };
 
     Errno::result(res)
 }
 
+#[deprecated(since = "0.27.0", note = "Use Epoll::new() instead")]
 #[inline]
 pub fn epoll_create1(flags: EpollCreateFlags) -> Result<RawFd> {
     let res = unsafe { libc::epoll_create1(flags.bits()) };
 
     Errno::result(res)
 }
 
+#[deprecated(since = "0.27.0", note = "Use Epoll::epoll_ctl() instead")]
 #[inline]
 pub fn epoll_ctl<'a, T>(
     epfd: RawFd,
@@ -102,13 +207,14 @@ where
             if let Some(ref mut event) = event {
                 libc::epoll_ctl(epfd, op as c_int, fd, &mut event.event)
             } else {
-                libc::epoll_ctl(epfd, op as c_int, fd, ptr::null_mut())
+                libc::epoll_ctl(epfd, op as c_int, fd, std::ptr::null_mut())
             }
         };
         Errno::result(res).map(drop)
     }
 }
 
+#[deprecated(since = "0.27.0", note = "Use Epoll::wait() instead")]
 #[inline]
 pub fn epoll_wait(
     epfd: RawFd,
@@ -125,4 +231,4 @@ pub fn epoll_wait(
     };
 
     Errno::result(res).map(|r| r as usize)
-}
+}

test/sys/test_epoll.rs

@@ -1,9 +1,15 @@
+#![allow(deprecated)]
+
+use std::os::unix::io::{OwnedFd,FromRawFd};
+
 use nix::errno::Errno;
 use nix::sys::epoll::{epoll_create1, epoll_ctl};
-use nix::sys::epoll::{EpollCreateFlags, EpollEvent, EpollFlags, EpollOp};
+use nix::sys::epoll::{
+    Epoll, EpollCreateFlags, EpollEvent, EpollFlags, EpollOp,
+};
 
 #[test]
-pub fn test_epoll_errno() {
+pub fn test_deprecated_epoll_errno() {
     let efd = epoll_create1(EpollCreateFlags::empty()).unwrap();
     let result = epoll_ctl(efd, EpollOp::EpollCtlDel, 1, None);
     result.expect_err("assertion failed");
@@ -15,10 +21,28 @@ pub fn test_epoll_errno() {
 }
 
 #[test]
-pub fn test_epoll_ctl() {
+pub fn test_deprecated_epoll_ctl() {
     let efd = epoll_create1(EpollCreateFlags::empty()).unwrap();
     let mut event =
         EpollEvent::new(EpollFlags::EPOLLIN | EpollFlags::EPOLLERR, 1);
     epoll_ctl(efd, EpollOp::EpollCtlAdd, 1, &mut event).unwrap();
     epoll_ctl(efd, EpollOp::EpollCtlDel, 1, None).unwrap();
 }
+
+#[test]
+pub fn test_epoll_errno() {
+    let efd = Epoll::new(EpollCreateFlags::empty()).unwrap();
+    let fd = unsafe { OwnedFd::from_raw_fd(1) };
+    let result = efd.delete(&fd);
+    assert_eq!(result, Err(Errno::ENOENT));
+}
+
+#[test]
+pub fn test_epoll_ctl() {
+    let efd = Epoll::new(EpollCreateFlags::empty()).unwrap();
+    let fd = unsafe { OwnedFd::from_raw_fd(1) };
+    let event =
+        EpollEvent::new(EpollFlags::EPOLLIN | EpollFlags::EPOLLERR, 1);
+    efd.add(&fd, event).unwrap();
+    efd.delete(&fd).unwrap();
+}