event: add kevent64 support on apple targets (#2781)

* event: add kevent64 support on apple targets

Add KEvent64, Kevent64Flags, and Kqueue::kevent64 wrapping the
kevent64 syscall available on apple platforms. This uses fixed-width
64-bit fields and provides an additional ext field for filter-specific
data.

* docs: correct doc of struct KEvent

* test: Kqueue.kevent64()

---------

Co-authored-by: Steve Lau <stevelauc@outlook.com>

Author: kamalmarhubi

Cargo.toml

@@ -27,7 +27,7 @@ targets = [
 ]
 
 [dependencies]
-libc = { version = "0.2.183", features = ["extra_traits"] }
+libc = { version = "0.2.186", features = ["extra_traits"] }
 bitflags = "2.3.3"
 cfg-if = "1.0"
 pin-utils = { version = "0.1.0", optional = true }

changelog/2781.added.md

@@ -0,0 +1 @@
+Added `kevent64` support on apple targets: `Kqueue::kevent64`, `KEvent64`, and `Kevent64Flags`.

src/sys/event.rs

@@ -14,14 +14,21 @@ use std::os::fd::{AsFd, BorrowedFd};
 use std::os::unix::io::{AsRawFd, FromRawFd, OwnedFd};
 use std::ptr;
 
-/// A kernel event queue.  Used to notify a process of various asynchronous
-/// events.
+/// An event for use with [`Kqueue::kevent`].
 #[repr(C)]
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 pub struct KEvent {
     kevent: libc::kevent,
 }
 
+/// An event for use with [`Kqueue::kevent64`].
+#[cfg(apple_targets)]
+#[repr(transparent)]
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub struct KEvent64 {
+    kevent: libc::kevent64_s,
+}
+
 /// A kernel event queue.
 ///
 /// Used by the kernel to notify the process of various types of asynchronous
@@ -89,6 +96,33 @@ impl Kqueue {
         };
         Errno::result(res).map(|r| r as usize)
     }
+
+    /// Like [`kevent`](Kqueue::kevent), but uses [`KEvent64`].
+    #[cfg(apple_targets)]
+    pub fn kevent64(
+        &self,
+        changelist: &[KEvent64],
+        eventlist: &mut [KEvent64],
+        flags: Kevent64Flags,
+        timeout_opt: Option<timespec>,
+    ) -> Result<usize> {
+        let res = unsafe {
+            libc::kevent64(
+                self.0.as_raw_fd(),
+                changelist.as_ptr().cast(),
+                changelist.len() as c_int,
+                eventlist.as_mut_ptr().cast(),
+                eventlist.len() as c_int,
+                flags.bits(),
+                if let Some(ref timeout) = timeout_opt {
+                    timeout as *const timespec
+                } else {
+                    ptr::null()
+                },
+            )
+        };
+        Errno::result(res).map(|r| r as usize)
+    }
 }
 
 #[cfg(target_os = "netbsd")]
@@ -328,6 +362,17 @@ libc_bitflags!(
     }
 );
 
+#[cfg(apple_targets)]
+libc_bitflags! {
+    /// Flags for [`Kqueue::kevent64`].
+    pub struct Kevent64Flags: libc::c_uint {
+        /// Return immediately even if there are no events to return.
+        KEVENT_FLAG_IMMEDIATE;
+        /// Only return error events from the changelist.
+        KEVENT_FLAG_ERROR_EVENTS;
+    }
+}
+
 #[allow(missing_docs)]
 #[deprecated(since = "0.27.0", note = "Use KEvent::new instead")]
 pub fn kqueue() -> Result<Kqueue> {
@@ -401,6 +446,75 @@ impl KEvent {
     }
 }
 
+#[cfg(apple_targets)]
+const _: () = {
+    fn _assert_send<T: Send>() {}
+    fn _assert() {
+        _assert_send::<KEvent64>();
+    }
+};
+
+#[cfg(apple_targets)]
+impl KEvent64 {
+    /// Construct a new `KEvent64`.
+    pub fn new(
+        ident: u64,
+        filter: EventFilter,
+        flags: EvFlags,
+        fflags: FilterFlag,
+        data: i64,
+        udata: u64,
+        ext: [u64; 2],
+    ) -> KEvent64 {
+        KEvent64 {
+            kevent: libc::kevent64_s {
+                ident,
+                filter: filter as type_of_event_filter,
+                flags: flags.bits(),
+                fflags: fflags.bits(),
+                data,
+                udata,
+                ext,
+            },
+        }
+    }
+
+    /// Value used to identify this event.
+    pub fn ident(&self) -> u64 {
+        self.kevent.ident
+    }
+
+    /// Identifies the kernel filter used to process this event.
+    pub fn filter(&self) -> Result<EventFilter> {
+        self.kevent.filter.try_into()
+    }
+
+    /// Event flags.
+    pub fn flags(&self) -> EvFlags {
+        EvFlags::from_bits_retain(self.kevent.flags)
+    }
+
+    /// Filter-specific flags.
+    pub fn fflags(&self) -> FilterFlag {
+        FilterFlag::from_bits_retain(self.kevent.fflags)
+    }
+
+    /// Filter-specific data value.
+    pub fn data(&self) -> i64 {
+        self.kevent.data
+    }
+
+    /// Opaque user-defined value passed through the kernel unchanged.
+    pub fn udata(&self) -> u64 {
+        self.kevent.udata
+    }
+
+    /// Filter-specific extension data.
+    pub fn ext(&self) -> [u64; 2] {
+        self.kevent.ext
+    }
+}
+
 #[allow(missing_docs)]
 #[deprecated(since = "0.27.0", note = "Use Kqueue::kevent instead")]
 pub fn kevent(

test/sys/test_event.rs

@@ -1,5 +1,7 @@
 use libc::intptr_t;
 use nix::sys::event::{EvFlags, EventFilter, FilterFlag, KEvent};
+#[cfg(apple_targets)]
+use nix::sys::event::{KEvent64, Kevent64Flags, Kqueue};
 
 #[test]
 fn test_struct_kevent() {
@@ -25,6 +27,33 @@ fn test_struct_kevent() {
     assert_eq!(mem::size_of::<libc::kevent>(), mem::size_of::<KEvent>());
 }
 
+#[cfg(apple_targets)]
+#[test]
+fn test_struct_kevent64() {
+    use std::mem;
+
+    let actual = KEvent64::new(
+        0xdead_beef,
+        EventFilter::EVFILT_READ,
+        EvFlags::EV_ONESHOT | EvFlags::EV_ADD,
+        FilterFlag::NOTE_CHILD | FilterFlag::NOTE_EXIT,
+        0x1337,
+        12345,
+        [0xaa, 0xbb],
+    );
+    assert_eq!(0xdead_beef, actual.ident());
+    assert_eq!(EventFilter::EVFILT_READ, actual.filter().unwrap());
+    assert_eq!(libc::EV_ONESHOT | libc::EV_ADD, actual.flags().bits());
+    assert_eq!(libc::NOTE_CHILD | libc::NOTE_EXIT, actual.fflags().bits());
+    assert_eq!(0x1337, actual.data());
+    assert_eq!(12345, actual.udata());
+    assert_eq!([0xaa, 0xbb], actual.ext());
+    assert_eq!(
+        mem::size_of::<libc::kevent64_s>(),
+        mem::size_of::<KEvent64>()
+    );
+}
+
 #[test]
 fn test_kevent_filter() {
     let udata: intptr_t = 12345;
@@ -39,3 +68,22 @@ fn test_kevent_filter() {
     );
     assert_eq!(EventFilter::EVFILT_READ, actual.filter().unwrap());
 }
+
+#[test]
+#[cfg(apple_targets)]
+fn kevent64_empty_lists_zero_timeout() {
+    let kq = Kqueue::new().expect("failed to create kqueue");
+    let changelist: [KEvent64; 0] = [];
+    let mut eventlist: [KEvent64; 0] = [];
+    let timeout = libc::timespec {
+        tv_sec: 0,
+        tv_nsec: 0,
+    };
+    let result = kq.kevent64(
+        &changelist,
+        &mut eventlist,
+        Kevent64Flags::empty(),
+        Some(timeout),
+    );
+    assert_eq!(result.expect("kevent64 should succeed"), 0);
+}