Implement the new module structure for shm and inotify (#1127)

* Implement the new module structure for shm and inotify

Signed-off-by: Alex Saveau <saveau.alexandre@gmail.com>

* Use module prefixes in the docs for shm and inotify

Signed-off-by: Alex Saveau <saveau.alexandre@gmail.com>

* Fix inotify names for new module structure

Signed-off-by: Alex Saveau <saveau.alexandre@gmail.com>

---------

Signed-off-by: Alex Saveau <saveau.alexandre@gmail.com>

Author: SUPERCILEX

src/backend/libc/fs/inotify.rs

@@ -4,9 +4,9 @@ use crate::backend::c;
 use bitflags::bitflags;
 
 bitflags! {
-    /// `IN_*` for use with [`inotify_init`].
+    /// `IN_*` for use with [`inotify::init`].
     ///
-    /// [`inotify_init`]: crate::fs::inotify::inotify_init
+    /// [`inotify::init`]: crate::fs::inotify::init
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct CreateFlags: u32 {
@@ -21,9 +21,9 @@ bitflags! {
 }
 
 bitflags! {
-    /// `IN*` for use with [`inotify_add_watch`].
+    /// `IN*` for use with [`inotify::add_watch`].
     ///
-    /// [`inotify_add_watch`]: crate::fs::inotify::inotify_add_watch
+    /// [`inotify::add_watch`]: crate::fs::inotify::add_watch
     #[repr(transparent)]
     #[derive(Default, Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct WatchFlags: u32 {
@@ -78,9 +78,9 @@ bitflags! {
 }
 
 bitflags! {
-    /// `IN*` for use with [`InotifyReader`].
+    /// `IN*` for use with [`inotify::Reader`].
     ///
-    /// [`InotifyReader`]: crate::fs::inotify::InotifyReader
+    /// [`inotify::Reader`]: crate::fs::inotify::Reader
     #[repr(transparent)]
     #[derive(Default, Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct ReadFlags: u32 {

src/backend/libc/shm/types.rs

@@ -2,9 +2,9 @@ use crate::backend::c;
 use bitflags::bitflags;
 
 bitflags! {
-    /// `O_*` constants for use with [`shm_open`].
+    /// `O_*` constants for use with [`shm::open`].
     ///
-    /// [`shm_open`]: crate:shm::shm_open
+    /// [`shm::open`]: crate:shm::open
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct ShmOFlags: u32 {

src/backend/linux_raw/fs/inotify.rs

@@ -4,9 +4,9 @@ use crate::backend::c;
 use bitflags::bitflags;
 
 bitflags! {
-    /// `IN_*` for use with [`inotify_init`].
+    /// `IN_*` for use with [`inotify::init`].
     ///
-    /// [`inotify_init`]: crate::fs::inotify::inotify_init
+    /// [`inotify::init`]: crate::fs::inotify::init
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct CreateFlags: c::c_uint {
@@ -21,9 +21,9 @@ bitflags! {
 }
 
 bitflags! {
-    /// `IN*` for use with [`inotify_add_watch`].
+    /// `IN*` for use with [`inotify::add_watch`].
     ///
-    /// [`inotify_add_watch`]: crate::fs::inotify::inotify_add_watch
+    /// [`inotify::add_watch`]: crate::fs::inotify::add_watch
     #[repr(transparent)]
     #[derive(Default, Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct WatchFlags: c::c_uint {
@@ -78,9 +78,9 @@ bitflags! {
 }
 
 bitflags! {
-    /// `IN*` for use with [`InotifyReader`].
+    /// `IN*` for use with [`inotify::Reader`].
     ///
-    /// [`InotifyReader`]: crate::fs::inotify::InotifyReader
+    /// [`inotify::Reader`]: crate::fs::inotify::InotifyReader
     #[repr(transparent)]
     #[derive(Default, Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct ReadFlags: c::c_uint {

src/backend/linux_raw/shm/types.rs

@@ -2,9 +2,9 @@ use crate::backend::c;
 use bitflags::bitflags;
 
 bitflags! {
-    /// `O_*` constants for use with [`shm_open`].
+    /// `O_*` constants for use with [`shm::open`].
     ///
-    /// [`shm_open`]: crate:shm::shm_open
+    /// [`shm::open`]: crate:shm::open
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct ShmOFlags: c::c_uint {

src/fs/inotify.rs

@@ -1,5 +1,8 @@
 //! inotify support for working with inotifies
 
+#![allow(unused_qualifications)]
+
+use super::inotify;
 pub use crate::backend::fs::inotify::{CreateFlags, ReadFlags, WatchFlags};
 use crate::backend::fs::syscalls;
 use crate::fd::{AsFd, OwnedFd};
@@ -9,13 +12,23 @@ use crate::io::{read_uninit, Errno};
 use core::mem::{align_of, size_of, MaybeUninit};
 use linux_raw_sys::general::inotify_event;
 
+#[deprecated(note = "Use add_watch.")]
+#[doc(hidden)]
+pub use add_watch as inotify_add_watch;
+#[deprecated(note = "Use init.")]
+#[doc(hidden)]
+pub use init as inotify_init;
+#[deprecated(note = "Use remove_watch.")]
+#[doc(hidden)]
+pub use remove_watch as inotify_remove_watch;
+
 /// `inotify_init1(flags)`—Creates a new inotify object.
 ///
 /// Use the [`CreateFlags::CLOEXEC`] flag to prevent the resulting file
 /// descriptor from being implicitly passed across `exec` boundaries.
 #[doc(alias = "inotify_init1")]
 #[inline]
-pub fn inotify_init(flags: CreateFlags) -> io::Result<OwnedFd> {
+pub fn init(flags: inotify::CreateFlags) -> io::Result<OwnedFd> {
     syscalls::inotify_init1(flags)
 }
 
@@ -27,22 +40,23 @@ pub fn inotify_init(flags: CreateFlags) -> io::Result<OwnedFd> {
 /// Note: Due to the existence of hardlinks, providing two different paths to
 /// this method may result in it returning the same watch descriptor. An
 /// application should keep track of this externally to avoid logic errors.
+#[doc(alias = "inotify_add_watch")]
 #[inline]
-pub fn inotify_add_watch<P: crate::path::Arg>(
+pub fn add_watch<P: crate::path::Arg>(
     inot: impl AsFd,
     path: P,
-    flags: WatchFlags,
+    flags: inotify::WatchFlags,
 ) -> io::Result<i32> {
     path.into_with_c_str(|path| syscalls::inotify_add_watch(inot.as_fd(), path, flags))
 }
 
 /// `inotify_rm_watch(self, wd)`—Removes a watch from this inotify.
 ///
 /// The watch descriptor provided should have previously been returned by
-/// [`inotify_add_watch`] and not previously have been removed.
+/// [`inotify::add_watch`] and not previously have been removed.
 #[doc(alias = "inotify_rm_watch")]
 #[inline]
-pub fn inotify_remove_watch(inot: impl AsFd, wd: i32) -> io::Result<()> {
+pub fn remove_watch(inot: impl AsFd, wd: i32) -> io::Result<()> {
     syscalls::inotify_rm_watch(inot.as_fd(), wd)
 }
 
@@ -52,14 +66,14 @@ pub fn inotify_remove_watch(inot: impl AsFd, wd: i32) -> io::Result<()> {
 /// based on it.
 ///
 /// [`RawDir`]: crate::fs::raw_dir::RawDir
-pub struct InotifyReader<'buf, Fd: AsFd> {
+pub struct Reader<'buf, Fd: AsFd> {
     fd: Fd,
     buf: &'buf mut [MaybeUninit<u8>],
     initialized: usize,
     offset: usize,
 }
 
-impl<'buf, Fd: AsFd> InotifyReader<'buf, Fd> {
+impl<'buf, Fd: AsFd> Reader<'buf, Fd> {
     /// Create a new iterator from the given file descriptor and buffer.
     pub fn new(fd: Fd, buf: &'buf mut [MaybeUninit<u8>]) -> Self {
         Self {
@@ -114,7 +128,7 @@ impl<'a> InotifyEvent<'a> {
     }
 }
 
-impl<'buf, Fd: AsFd> InotifyReader<'buf, Fd> {
+impl<'buf, Fd: AsFd> Reader<'buf, Fd> {
     /// Read the next inotify event.
     #[allow(unsafe_code)]
     pub fn next(&mut self) -> io::Result<InotifyEvent> {

src/shm.rs

@@ -1,18 +1,30 @@
 //! POSIX shared memory
 
+#![allow(unused_qualifications)]
+
 use crate::fd::OwnedFd;
 use crate::{backend, io, path};
 
+use super::shm;
 pub use crate::backend::fs::types::Mode;
+pub use crate::backend::shm::types::ShmOFlags as OFlags;
+#[deprecated(note = "Use OFlags.")]
+#[doc(hidden)]
 pub use crate::backend::shm::types::ShmOFlags;
+#[deprecated(note = "Use open.")]
+#[doc(hidden)]
+pub use open as shm_open;
+#[deprecated(note = "Use unlink.")]
+#[doc(hidden)]
+pub use unlink as shm_unlink;
 
 /// `shm_open(name, oflags, mode)`—Opens a shared memory object.
 ///
 /// For portability, `name` should begin with a slash, contain no other
 /// slashes, and be no longer than an implementation-defined limit (255 on
 /// Linux).
 ///
-/// Exactly one of [`ShmOFlags::RDONLY`] and [`ShmOFlags::RDWR`] should be
+/// Exactly one of [`shm::OFlags::RDONLY`] and [`shm::OFlags::RDWR`] should be
 /// passed. The file descriptor will be opened with `FD_CLOEXEC` set.
 ///
 /// # References
@@ -21,8 +33,9 @@ pub use crate::backend::shm::types::ShmOFlags;
 ///
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/shm_open.html
 /// [Linux]: https://man7.org/linux/man-pages/man3/shm_open.3.html
+#[doc(alias = "shm_open")]
 #[inline]
-pub fn shm_open<P: path::Arg>(name: P, flags: ShmOFlags, mode: Mode) -> io::Result<OwnedFd> {
+pub fn open<P: path::Arg>(name: P, flags: shm::OFlags, mode: Mode) -> io::Result<OwnedFd> {
     name.into_with_c_str(|name| backend::shm::syscalls::shm_open(name, flags, mode))
 }
 
@@ -34,7 +47,8 @@ pub fn shm_open<P: path::Arg>(name: P, flags: ShmOFlags, mode: Mode) -> io::Resu
 ///
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/shm_unlink.html
 /// [Linux]: https://man7.org/linux/man-pages/man3/shm_unlink.3.html
+#[doc(alias = "shm_unlink")]
 #[inline]
-pub fn shm_unlink<P: path::Arg>(name: P) -> io::Result<()> {
+pub fn unlink<P: path::Arg>(name: P) -> io::Result<()> {
     name.into_with_c_str(backend::shm::syscalls::shm_unlink)
 }

tests/fs/inotify.rs

@@ -1,16 +1,14 @@
-use rustix::fs::inotify::{
-    inotify_add_watch, inotify_init, CreateFlags, InotifyReader, WatchFlags,
-};
+use rustix::fs::inotify::{self, CreateFlags, WatchFlags};
 use rustix::io::Errno;
 use std::fmt::Write;
 use std::fs::{create_dir_all, remove_file, rename, File};
 use std::mem::MaybeUninit;
 
 #[test]
 fn test_inotify_iter() {
-    let inotify = inotify_init(CreateFlags::NONBLOCK).unwrap();
+    let inotify = inotify::init(CreateFlags::NONBLOCK).unwrap();
     create_dir_all("/tmp/.rustix-inotify-test").unwrap();
-    inotify_add_watch(
+    inotify::add_watch(
         &inotify,
         "/tmp/.rustix-inotify-test",
         WatchFlags::ALL_EVENTS,
@@ -29,7 +27,7 @@ fn test_inotify_iter() {
     let mut cookie = 0;
 
     let mut buf = [MaybeUninit::uninit(); 512];
-    let mut iter = InotifyReader::new(inotify, &mut buf);
+    let mut iter = inotify::Reader::new(inotify, &mut buf);
     loop {
         let e = match iter.next() {
             Err(Errno::WOULDBLOCK) => break,