feat: rework PathsMut to be more consistent

CHANGELOG.md

@@ -3,9 +3,11 @@
 ## notify 8.2.0 (unreleased)
 - FEATURE: notify a user if the `max_user_watches` has been reached implicitly (`INotifyWatcher`) [#698]
 - FIX: `INotifyWatcher` ignores events with unknown watch descriptors (instead of `EventMask::Q_OVERFLOW`) [#700]
+- FEATURE: deprecate `Watcher::paths_mut` and introduce `update_paths` [#705]
 
 [#698]: https://github.com/notify-rs/notify/pull/698
 [#700]: https://github.com/notify-rs/notify/pull/700
+[#705]: https://github.com/notify-rs/notify/pull/705
 
 ## notify 8.1.0 (2025-07-03)
 - FEATURE: added support for the [`flume`](https://docs.rs/flume) crate

notify/src/config.rs

@@ -1,6 +1,6 @@
 //! Configuration types
 
-use std::time::Duration;
+use std::{path::PathBuf, time::Duration};
 
 /// Indicates whether only the provided directory or its sub-directories as well should be watched
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
@@ -123,3 +123,62 @@ impl Default for Config {
         }
     }
 }
+
+/// Single watch backend configuration
+///
+/// This contains some settings that may relate to only one specific backend,
+/// such as to correctly configure each backend regardless of what is selected during runtime.
+#[derive(Debug)]
+pub struct WatchPathConfig {
+    recursive_mode: RecursiveMode,
+}
+
+impl WatchPathConfig {
+    /// Creates new instance with provided [`RecursiveMode`]
+    pub fn new(recursive_mode: RecursiveMode) -> Self {
+        Self { recursive_mode }
+    }
+
+    /// Set [`RecursiveMode`] for the watch
+    pub fn with_recursive_mode(mut self, recursive_mode: RecursiveMode) -> Self {
+        self.recursive_mode = recursive_mode;
+        self
+    }
+
+    /// Returns current setting
+    pub fn recursive_mode(&self) -> RecursiveMode {
+        self.recursive_mode
+    }
+}
+
+/// An operation to apply to a watcher
+///
+/// See [`Watcher::update_paths`] for more information
+#[derive(Debug)]
+pub enum PathOp {
+    /// Path should be watcher
+    Watch(PathBuf, WatchPathConfig),
+
+    /// Path should be unwatched
+    Unwatch(PathBuf),
+}
+
+impl PathOp {
+    /// Watch the path with [`RecursiveMode::Recursive`]
+    pub fn watch_recursive<P: Into<PathBuf>>(path: P) -> Self {
+        Self::Watch(path.into(), WatchPathConfig::new(RecursiveMode::Recursive))
+    }
+
+    /// Watch the path with [`RecursiveMode::NonRecursive`]
+    pub fn watch_non_recursive<P: Into<PathBuf>>(path: P) -> Self {
+        Self::Watch(
+            path.into(),
+            WatchPathConfig::new(RecursiveMode::NonRecursive),
+        )
+    }
+
+    /// Unwatch the path
+    pub fn unwatch<P: Into<PathBuf>>(path: P) -> Self {
+        Self::Unwatch(path.into())
+    }
+}

notify/src/error.rs

@@ -1,7 +1,8 @@
 //! Error types
 
-use crate::Config;
+use crate::{Config, PathOp};
 use std::error::Error as StdError;
+use std::fmt::Debug;
 use std::path::PathBuf;
 use std::result::Result as StdResult;
 use std::{self, fmt, io};
@@ -158,14 +159,61 @@ impl<T> From<std::sync::PoisonError<T>> for Error {
     }
 }
 
-#[test]
-fn display_formatted_errors() {
-    let expected = "Some error";
+/// The error provided by [`crate::Watcher::update_paths`] method
+#[derive(Debug)]
+pub struct UpdatePathsError {
+    /// The original error
+    pub source: Error,
+
+    /// The remaining operations that haven't been applied
+    pub remaining: Vec<PathOp>,
+}
+
+impl fmt::Display for UpdatePathsError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "unable to apply the batch operation: {}", self.source)
+    }
+}
 
-    assert_eq!(expected, format!("{}", Error::generic(expected)));
+impl StdError for UpdatePathsError {
+    fn source(&self) -> Option<&(dyn StdError + 'static)> {
+        Some(&self.source)
+    }
+}
 
-    assert_eq!(
-        expected,
-        format!("{}", Error::io(io::Error::other(expected)))
-    );
+impl From<UpdatePathsError> for Error {
+    fn from(value: UpdatePathsError) -> Self {
+        value.source
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn display_formatted_errors() {
+        let expected = "Some error";
+
+        assert_eq!(expected, format!("{}", Error::generic(expected)));
+
+        assert_eq!(
+            expected,
+            format!("{}", Error::io(io::Error::other(expected)))
+        );
+    }
+
+    #[test]
+    fn display_update_paths() {
+        let actual = UpdatePathsError {
+            source: Error::generic("Some error"),
+            remaining: Default::default(),
+        }
+        .to_string();
+
+        assert_eq!(
+            format!("unable to apply the batch operation: Some error"),
+            actual
+        );
+    }
 }

notify/src/fsevent.rs

@@ -14,10 +14,8 @@
 
 #![allow(non_upper_case_globals, dead_code)]
 
-use crate::event::*;
-use crate::{
-    unbounded, Config, Error, EventHandler, PathsMut, RecursiveMode, Result, Sender, Watcher,
-};
+use crate::{event::*, PathOp};
+use crate::{unbounded, Config, Error, EventHandler, RecursiveMode, Result, Sender, Watcher};
 use fsevent_sys as fs;
 use fsevent_sys::core_foundation as cf;
 use std::collections::HashMap;
@@ -267,29 +265,6 @@ extern "C" {
     fn CFRunLoopIsWaiting(runloop: cf::CFRunLoopRef) -> cf::Boolean;
 }
 
-struct FsEventPathsMut<'a>(&'a mut FsEventWatcher);
-impl<'a> FsEventPathsMut<'a> {
-    fn new(watcher: &'a mut FsEventWatcher) -> Self {
-        watcher.stop();
-        Self(watcher)
-    }
-}
-impl PathsMut for FsEventPathsMut<'_> {
-    fn add(&mut self, path: &Path, recursive_mode: RecursiveMode) -> Result<()> {
-        self.0.append_path(path, recursive_mode)
-    }
-
-    fn remove(&mut self, path: &Path) -> Result<()> {
-        self.0.remove_path(path)
-    }
-
-    fn commit(self: Box<Self>) -> Result<()> {
-        // ignore return error: may be empty path list
-        let _ = self.0.run();
-        Ok(())
-    }
-}
-
 impl FsEventWatcher {
     fn from_event_handler(event_handler: Arc<Mutex<dyn EventHandler>>) -> Result<Self> {
         Ok(FsEventWatcher {
@@ -321,6 +296,23 @@ impl FsEventWatcher {
         result
     }
 
+    fn update_paths_inner(
+        &mut self,
+        ops: Vec<crate::PathOp>,
+    ) -> crate::StdResult<(), crate::UpdatePathsError> {
+        self.stop();
+
+        let result = crate::update_paths(ops, |op| match op {
+            crate::PathOp::Watch(path, config) => self.append_path(&path, config.recursive_mode()),
+            crate::PathOp::Unwatch(path) => self.remove_path(&path),
+        });
+
+        // ignore return error: may be empty path list
+        let _ = self.run();
+
+        result
+    }
+
     #[inline]
     fn is_running(&self) -> bool {
         self.runloop.is_some()
@@ -586,14 +578,14 @@ impl Watcher for FsEventWatcher {
         self.watch_inner(path, recursive_mode)
     }
 
-    fn paths_mut<'me>(&'me mut self) -> Box<dyn PathsMut + 'me> {
-        Box::new(FsEventPathsMut::new(self))
-    }
-
     fn unwatch(&mut self, path: &Path) -> Result<()> {
         self.unwatch_inner(path)
     }
 
+    fn update_paths(&mut self, ops: Vec<PathOp>) -> crate::StdResult<(), crate::UpdatePathsError> {
+        self.update_paths_inner(ops)
+    }
+
     fn configure(&mut self, config: Config) -> Result<bool> {
         let (tx, rx) = unbounded();
         self.configure_raw_mode(config, tx);