Introduce a new Buffer trait. (#1290)

Using the idea from #908 and #1110, introduce a new `Buffer` trait for
reading into possibly uninitialized buffers, and use it in `read`,
`recv`, `epoll::wait`, `kqueue`, `getxattr`, and several other
functions.

This eliminates the need for separate `*_uninit` functions

Author: sunfishcode

CHANGES.md

@@ -273,5 +273,35 @@ a `[MaybeUninit<u8>]` instead of a `[u8]`.
 [`SendAncillaryBuffer`]: https://docs.rs/rustix/1.0.0/rustix/net/struct.SendAncillaryBuffer.html
 [`RecvAncillaryBuffer`]: https://docs.rs/rustix/1.0.0/rustix/net/struct.RecvAncillaryBuffer.html
 
+[`read`], [`pread`], [`recv`], [`recvfrom`], [`getrandom`], [`epoll::wait`],
+[`kqueue`], [`getxattr`], [`lgetxattr`], [`fgetxattr`], [`listxattr`],
+[`llistxattr`], and [`flistxattr`] now use the new [`Buffer` trait].
+
+This replaces `read_uninit`, `pread_uninit`, `recv_uninit`, `recvfrom_uninit`,
+and `getrandom_uninit`, as the `Buffer` trait supports reading into
+uninitialized slices.
+
+`epoll::wait` and `kqueue` previously took a `Vec` which it implicitly cleared
+before results were appended. When passing a `Vec` to `epoll::wait` or `kqueue`
+using [`spare_capacity`], the `Vec` is not cleared first. Consider clearing the
+vector before calling `epoll::wait` or `kqueue`, or consuming it using
+`.drain(..)` before reusing it.
+
+[`read`]: https://docs.rs/rustix/1.0.0/rustix/io/fn.read.html
+[`pread`]: https://docs.rs/rustix/1.0.0/rustix/io/fn.pread.html
+[`recv`]: https://docs.rs/rustix/1.0.0/rustix/net/fn.recv.html
+[`recvfrom`]: https://docs.rs/rustix/1.0.0/rustix/net/fn.recvfrom.html
+[`getrandom`]: https://docs.rs/rustix/1.0.0/rustix/rand/fn.getrandom.html
+[`epoll::wait`]: https://docs.rs/rustix/1.0.0/rustix/event/epoll/fn.wait.html
+[`getxattr`]: https://docs.rs/rustix/1.0.0/rustix/fs/fn.getxattr.html
+[`lgetxattr`]: https://docs.rs/rustix/1.0.0/rustix/fs/fn.lgetxattr.html
+[`fgetxattr`]: https://docs.rs/rustix/1.0.0/rustix/fs/fn.fgetxattr.html
+[`listxattr`]: https://docs.rs/rustix/1.0.0/rustix/fs/fn.listxattr.html
+[`llistxattr`]: https://docs.rs/rustix/1.0.0/rustix/fs/fn.llistxattr.html
+[`flistxattr`]: https://docs.rs/rustix/1.0.0/rustix/fs/fn.flistxattr.html
+[`kqueue`]: https://docs.rs/rustix/1.0.0/x86_64-unknown-freebsd/rustix/event/kqueue/fn.kqueue.html
+[`Buffer` trait]: https://docs.rs/rustix/1.0.0/rustix/buffer/trait.Buffer.html
+[`spare_capacity`]: https://docs.rs/rustix/1.0.0/rustix/buffer/fn.spare_capacity.html
+
 All explicitly deprecated functions and types have been removed. Their
 deprecation messages will have identified alternatives.

examples/kq.rs

@@ -2,6 +2,7 @@
 
 #[cfg(all(bsd, feature = "event"))]
 fn main() -> std::io::Result<()> {
+    use rustix::buffer::spare_capacity;
     use rustix::event::kqueue::*;
     #[cfg(feature = "fs")]
     use rustix::{fd::AsRawFd, fs};
@@ -60,7 +61,7 @@ fn main() -> std::io::Result<()> {
     eprintln!("Run with --features process to enable more!");
     #[cfg(not(feature = "fs"))]
     eprintln!("Run with --features fs to enable more!");
-    unsafe { kevent(&kq, &subs, &mut out, None) }?;
+    unsafe { kevent(&kq, &subs, spare_capacity(&mut out), None) }?;
 
     loop {
         while let Some(e) = out.pop() {
@@ -80,7 +81,7 @@ fn main() -> std::io::Result<()> {
                 _ => eprintln!("Unknown event"),
             }
         }
-        unsafe { kevent(&kq, &[], &mut out, None) }?;
+        unsafe { kevent(&kq, &[], spare_capacity(&mut out), None) }?;
     }
 }
 

src/backend/libc/event/syscalls.rs

@@ -4,7 +4,6 @@ use crate::backend::c;
 #[cfg(any(linux_kernel, solarish, target_os = "redox"))]
 use crate::backend::conv::ret;
 use crate::backend::conv::ret_c_int;
-#[cfg(feature = "alloc")]
 #[cfg(any(linux_kernel, target_os = "illumos", target_os = "redox"))]
 use crate::backend::conv::ret_u32;
 #[cfg(solarish)]
@@ -24,11 +23,7 @@ use crate::io;
 use crate::utils::as_mut_ptr;
 #[cfg(any(linux_kernel, target_os = "illumos", target_os = "redox"))]
 use crate::utils::as_ptr;
-#[cfg(any(
-    all(feature = "alloc", bsd),
-    solarish,
-    all(feature = "alloc", any(linux_kernel, target_os = "redox")),
-))]
+#[cfg(solarish)]
 use core::mem::MaybeUninit;
 #[cfg(any(
     bsd,
@@ -107,7 +102,7 @@ pub(crate) fn kqueue() -> io::Result<OwnedFd> {
 pub(crate) unsafe fn kevent(
     kq: BorrowedFd<'_>,
     changelist: &[Event],
-    eventlist: &mut [MaybeUninit<Event>],
+    eventlist: (*mut Event, usize),
     timeout: Option<&c::timespec>,
 ) -> io::Result<c::c_int> {
     ret_c_int(c::kevent(
@@ -117,11 +112,8 @@ pub(crate) unsafe fn kevent(
             .len()
             .try_into()
             .map_err(|_| io::Errno::OVERFLOW)?,
-        eventlist.as_mut_ptr().cast(),
-        eventlist
-            .len()
-            .try_into()
-            .map_err(|_| io::Errno::OVERFLOW)?,
+        eventlist.0.cast(),
+        eventlist.1.try_into().map_err(|_| io::Errno::OVERFLOW)?,
         timeout.map_or(null(), as_ptr),
     ))
 }
@@ -512,11 +504,10 @@ pub(crate) fn epoll_del(epoll: BorrowedFd<'_>, source: BorrowedFd<'_>) -> io::Re
 }
 
 #[inline]
-#[cfg(feature = "alloc")]
 #[cfg(any(linux_kernel, target_os = "illumos", target_os = "redox"))]
-pub(crate) fn epoll_wait(
+pub(crate) unsafe fn epoll_wait(
     epoll: BorrowedFd<'_>,
-    events: &mut [MaybeUninit<crate::event::epoll::Event>],
+    events: (*mut crate::event::epoll::Event, usize),
     timeout: Option<&Timespec>,
 ) -> io::Result<usize> {
     // If we're on Linux >= 5.11 and a libc that has an `epoll_pwait2`
@@ -527,7 +518,7 @@ pub(crate) fn epoll_wait(
         target_env = "gnu",
         not(fix_y2038)
     ))]
-    unsafe {
+    {
         weak! {
             fn epoll_pwait2(
                 c::c_int,
@@ -541,8 +532,8 @@ pub(crate) fn epoll_wait(
         if let Some(epoll_pwait2_func) = epoll_pwait2.get() {
             return ret_u32(epoll_pwait2_func(
                 borrowed_fd(epoll),
-                events.as_mut_ptr().cast::<c::epoll_event>(),
-                events.len().try_into().unwrap_or(i32::MAX),
+                events.0.cast::<c::epoll_event>(),
+                events.1.try_into().unwrap_or(i32::MAX),
                 crate::utils::option_as_ptr(timeout).cast(),
                 null(),
             ))
@@ -552,7 +543,7 @@ pub(crate) fn epoll_wait(
 
     // If we're on Linux >= 5.11, use `epoll_pwait2` via `libc::syscall`.
     #[cfg(all(linux_kernel, feature = "linux_5_11"))]
-    unsafe {
+    {
         use linux_raw_sys::general::__kernel_timespec as timespec;
 
         syscall! {
@@ -567,8 +558,8 @@ pub(crate) fn epoll_wait(
 
         ret_u32(epoll_pwait2(
             borrowed_fd(epoll),
-            events.as_mut_ptr().cast::<c::epoll_event>(),
-            events.len().try_into().unwrap_or(i32::MAX),
+            events.0.cast::<c::epoll_event>(),
+            events.1.try_into().unwrap_or(i32::MAX),
             crate::utils::option_as_ptr(timeout).cast(),
             null(),
         ))
@@ -577,16 +568,16 @@ pub(crate) fn epoll_wait(
 
     // Otherwise just use `epoll_wait`.
     #[cfg(not(all(linux_kernel, feature = "linux_5_11")))]
-    unsafe {
+    {
         let timeout = match timeout {
             None => -1,
             Some(timeout) => timeout.as_c_int_millis().ok_or(io::Errno::INVAL)?,
         };
 
         ret_u32(c::epoll_wait(
             borrowed_fd(epoll),
-            events.as_mut_ptr().cast::<c::epoll_event>(),
-            events.len().try_into().unwrap_or(i32::MAX),
+            events.0.cast::<c::epoll_event>(),
+            events.1.try_into().unwrap_or(i32::MAX),
             timeout,
         ))
         .map(|i| i as usize)