From 5ad29467a2534ace999272764dc1b49c08266b4f Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 29 Jan 2025 19:29:22 -0800 Subject: [PATCH] Remove the `port_` and `Inotify` prefixes. (#1284) * Remove the `port_` and `Inotify` prefixes. `port_*` and `Inotify*` are in public modules named `port` and `inotify` so remove their prefixes to make them less redundant. * Name the `Examples` section in docs consistently. * Add a simple usage example for the port API. * Fix test output for inotify. * Add doc aliases for the port API. * Fix io_uring naming inconsistency. --- src/backend/linux_raw/conv.rs | 7 ++-- src/event/port.rs | 64 ++++++++++++++++++++++++++--------- src/fs/inotify.rs | 8 ++--- src/io_uring/mod.rs | 3 +- src/shm.rs | 2 +- tests/fs/inotify.rs | 12 +++---- 6 files changed, 62 insertions(+), 34 deletions(-) diff --git a/src/backend/linux_raw/conv.rs b/src/backend/linux_raw/conv.rs index 5459147ee..99342e09c 100644 --- a/src/backend/linux_raw/conv.rs +++ b/src/backend/linux_raw/conv.rs @@ -164,12 +164,9 @@ pub(super) unsafe fn raw_fd<'a, Num: ArgNumber>(fd: RawFd) -> ArgReg<'a, Num> { #[cfg(feature = "fs")] debug_assert!(fd == crate::fs::CWD.as_raw_fd() || fd == crate::fs::ABS.as_raw_fd() || fd >= 0); - // Don't pass the `IO_URING_REGISTER_FILES_SKIP` sentry value this way. + // Don't pass the `IORING_REGISTER_FILES_SKIP` sentry value this way. #[cfg(feature = "io_uring")] - debug_assert_ne!( - fd, - crate::io_uring::IO_URING_REGISTER_FILES_SKIP.as_raw_fd() - ); + debug_assert_ne!(fd, crate::io_uring::IORING_REGISTER_FILES_SKIP.as_raw_fd()); // Linux doesn't look at the high bits beyond the `c_int`, so use // zero-extension rather than sign-extension because it's a smaller diff --git a/src/event/port.rs b/src/event/port.rs index c50f76c73..b4e1da7ec 100644 --- a/src/event/port.rs +++ b/src/event/port.rs @@ -1,4 +1,31 @@ //! Solaris/illumos event ports. +//! +//! # Examples +//! +//! ``` +//! # fn test() -> std::io::Result<()> { +//! use rustix::event::port; +//! use rustix::stdio::stdout; +//! use std::io; +//! +//! let some_fd = stdout(); +//! let some_userdata = 7 as *mut _; +//! +//! // Create a port. +//! let port = port::create()?; +//! +//! // Associate `some_fd` with the port. +//! unsafe { +//! port::associate_fd(&port, some_fd, port::PollFlags::IN, some_userdata)?; +//! } +//! +//! // Get a single event. +//! let event = port::get(&port, None)?; +//! +//! assert_eq!(event.userdata(), some_userdata); +//! # Ok(()) +//! # } +//! ``` use crate::backend::c; use crate::backend::event::syscalls; @@ -6,12 +33,13 @@ use crate::fd::{AsFd, AsRawFd, OwnedFd}; use crate::ffi; use crate::io; -use super::PollFlags; - use core::time::Duration; +pub use super::PollFlags; + /// The structure representing a port event. #[repr(transparent)] +#[doc(alias = "port_event")] pub struct Event(pub(crate) c::port_event); impl Event { @@ -39,7 +67,8 @@ impl Event { /// /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_create/ /// [illumos]: https://illumos.org/man/3C/port_create -pub fn port_create() -> io::Result { +#[doc(alias = "port_create")] +pub fn create() -> io::Result { syscalls::port_create() } @@ -50,7 +79,7 @@ pub fn port_create() -> io::Result { /// /// Any `object`s passed into the `port` must be valid for the lifetime of the /// `port`. Logically, `port` keeps a borrowed reference to the `object` until -/// it is removed via `port_dissociate_fd`. +/// it is removed via [`dissociate_fd`]. /// /// # References /// - [OpenSolaris] @@ -58,7 +87,8 @@ pub fn port_create() -> io::Result { /// /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_associate/ /// [illumos]: https://illumos.org/man/3C/port_associate -pub unsafe fn port_associate_fd( +#[doc(alias = "port_associate")] +pub unsafe fn associate_fd( port: Fd, object: RawFd, events: PollFlags, @@ -79,7 +109,7 @@ pub unsafe fn port_associate_fd( /// # Safety /// /// The file descriptor passed into this function must have been previously -/// associated with the port via [`port_associate_fd`]. +/// associated with the port via [`associate_fd`]. /// /// # References /// - [OpenSolaris] @@ -87,10 +117,8 @@ pub unsafe fn port_associate_fd( /// /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_dissociate /// [illumos]: https://illumos.org/man/3C/port_dissociate -pub unsafe fn port_dissociate_fd( - port: Fd, - object: RawFd, -) -> io::Result<()> { +#[doc(alias = "port_dissociate")] +pub unsafe fn dissociate_fd(port: Fd, object: RawFd) -> io::Result<()> { syscalls::port_dissociate(port.as_fd(), c::PORT_SOURCE_FD, object.as_raw_fd() as _) } @@ -102,7 +130,8 @@ pub unsafe fn port_dissociate_fd( /// /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_get/ /// [illumos]: https://illumos.org/man/3C/port_get -pub fn port_get(port: Fd, timeout: Option) -> io::Result { +#[doc(alias = "port_get")] +pub fn get(port: Fd, timeout: Option) -> io::Result { let mut timeout = timeout.map(|timeout| c::timespec { tv_sec: timeout.as_secs().try_into().unwrap(), tv_nsec: timeout.subsec_nanos() as _, @@ -119,7 +148,7 @@ pub fn port_get(port: Fd, timeout: Option) -> io::Result(port: Fd, timeout: Option) -> io::Result( +#[doc(alias = "port_getn")] +pub fn getn( port: Fd, events: &mut Vec, min_events: usize, @@ -152,7 +182,7 @@ pub fn port_getn( /// `port_getn(port, NULL, 0, NULL)`—Queries the number of events /// available from a port. /// -/// To retrieve the events, use [`port_getn`]. +/// To retrieve the events, use [`getn`]. /// /// # References /// - [OpenSolaris] @@ -160,7 +190,8 @@ pub fn port_getn( /// /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_getn/ /// [illumos]: https://illumos.org/man/3C/port_getn -pub fn port_getn_query(port: Fd) -> io::Result { +#[doc(alias = "port_getn")] +pub fn getn_query(port: Fd) -> io::Result { syscalls::port_getn_query(port.as_fd()) } @@ -172,6 +203,7 @@ pub fn port_getn_query(port: Fd) -> io::Result { /// /// [OpenSolaris]: https://www.unix.com/man-page/opensolaris/3C/port_send/ /// [illumos]: https://illumos.org/man/3C/port_send -pub fn port_send(port: Fd, events: i32, userdata: *mut ffi::c_void) -> io::Result<()> { +#[doc(alias = "port_send")] +pub fn send(port: Fd, events: i32, userdata: *mut ffi::c_void) -> io::Result<()> { syscalls::port_send(port.as_fd(), events, userdata.cast()) } diff --git a/src/fs/inotify.rs b/src/fs/inotify.rs index f9fd900b8..c5f1df9ea 100644 --- a/src/fs/inotify.rs +++ b/src/fs/inotify.rs @@ -123,14 +123,14 @@ impl<'buf, Fd: AsFd> Reader<'buf, Fd> { /// An inotify event. #[derive(Debug)] -pub struct InotifyEvent<'a> { +pub struct Event<'a> { wd: i32, events: ReadFlags, cookie: u32, file_name: Option<&'a CStr>, } -impl<'a> InotifyEvent<'a> { +impl<'a> Event<'a> { /// Returns the watch for which this event occurs. #[inline] pub fn wd(&self) -> i32 { @@ -172,7 +172,7 @@ impl<'buf, Fd: AsFd> Reader<'buf, Fd> { /// error occurs. #[allow(unsafe_code)] #[allow(clippy::should_implement_trait)] - pub fn next(&mut self) -> io::Result> { + pub fn next(&mut self) -> io::Result> { if self.is_buffer_empty() { match read_uninit(self.fd.as_fd(), self.buf).map(|(init, _)| init.len()) { Ok(0) => return Err(Errno::INVAL), @@ -195,7 +195,7 @@ impl<'buf, Fd: AsFd> Reader<'buf, Fd> { self.offset += size_of::() + usize::try_from(event.len).unwrap(); - Ok(InotifyEvent { + Ok(Event { wd: event.wd, events: ReadFlags::from_bits_retain(event.mask), cookie: event.cookie, diff --git a/src/io_uring/mod.rs b/src/io_uring/mod.rs index 3473108ca..4158b14c9 100644 --- a/src/io_uring/mod.rs +++ b/src/io_uring/mod.rs @@ -912,11 +912,10 @@ pub const IORING_OFF_CQ_RING: u64 = sys::IORING_OFF_CQ_RING as _; pub const IORING_OFF_SQES: u64 = sys::IORING_OFF_SQES as _; /// `IORING_REGISTER_FILES_SKIP` -#[doc(alias = "IORING_REGISTER_FILES_SKIP")] // SAFETY: `IORING_REGISTER_FILES_SKIP` is a reserved value that is never // dynamically allocated, so it'll remain valid for the duration of // `'static`. -pub const IO_URING_REGISTER_FILES_SKIP: BorrowedFd<'static> = +pub const IORING_REGISTER_FILES_SKIP: BorrowedFd<'static> = unsafe { BorrowedFd::<'static>::borrow_raw(sys::IORING_REGISTER_FILES_SKIP as RawFd) }; /// `IORING_NOTIF_USAGE_ZC_COPIED` (since Linux 6.2) diff --git a/src/shm.rs b/src/shm.rs index e66c5737c..f279250d1 100644 --- a/src/shm.rs +++ b/src/shm.rs @@ -1,6 +1,6 @@ //! POSIX shared memory //! -//! # Example +//! # Examples //! //! ``` //! use rustix::fs::{ftruncate, Mode}; diff --git a/tests/fs/inotify.rs b/tests/fs/inotify.rs index 72fc7bde4..3200853f4 100644 --- a/tests/fs/inotify.rs +++ b/tests/fs/inotify.rs @@ -41,7 +41,7 @@ fn test_inotify_iter() { } let expected = format!( - r#"InotifyEvent {{ + r#"Event {{ wd: 1, events: ReadFlags( CREATE, @@ -51,7 +51,7 @@ fn test_inotify_iter() { "foo", ), }} -InotifyEvent {{ +Event {{ wd: 1, events: ReadFlags( OPEN, @@ -61,7 +61,7 @@ InotifyEvent {{ "foo", ), }} -InotifyEvent {{ +Event {{ wd: 1, events: ReadFlags( CLOSE_WRITE, @@ -71,7 +71,7 @@ InotifyEvent {{ "foo", ), }} -InotifyEvent {{ +Event {{ wd: 1, events: ReadFlags( MOVED_FROM, @@ -81,7 +81,7 @@ InotifyEvent {{ "foo", ), }} -InotifyEvent {{ +Event {{ wd: 1, events: ReadFlags( MOVED_TO, @@ -91,7 +91,7 @@ InotifyEvent {{ "bar", ), }} -InotifyEvent {{ +Event {{ wd: 1, events: ReadFlags( DELETE,