Add method for native watcher initialization with fallback

examples/Cargo.toml

@@ -33,7 +33,16 @@ path = "poll_sysfs.rs"
 name = "watcher_kind"
 path = "watcher_kind.rs"
 
+[[example]]
+name = "multiple_backends"
+path = "multiple_backends.rs"
+
 # specifically in its own sub folder
 # to prevent cargo audit from complaining
 #[[example]]
-#name = "hot_reload_tide"
+#name = "hot_reload_tide"
+
+# fix invalid rust-analyzer warnings
+# when changing notify but not updating the crates version
+[patch.crates-io]
+notify = { path = "../notify/" }

examples/multiple_backends.rs

@@ -0,0 +1,42 @@
+use notify::{RecursiveMode, Result, Watcher, Config};
+use std::path::Path;
+
+/// Initialize multiple backends via `recommended_watcher_fallback`
+fn fallback_init() -> Result<()> {
+    fn event_fn(res: Result<notify::Event>) {
+        match res {
+            Ok(event) => println!("event: {:?}", event),
+            Err(e) => println!("watch error: {:?}", e),
+        }
+    }
+
+    let mut watcher1 = notify::recommended_watcher_fallback(event_fn, Config::default())?;
+    // we will just use the same watcher kind again here
+    let mut watcher2 = notify::recommended_watcher_fallback(event_fn, Config::default())?;
+    watcher1.watch(Path::new("."), RecursiveMode::Recursive)?;
+    watcher2.watch(Path::new("."), RecursiveMode::Recursive)?;
+    Ok(())
+}
+
+/// Initialize multiple backends via recommended_watcher
+fn direct_init() -> Result<()> {
+    fn event_fn(res: Result<notify::Event>) {
+        match res {
+            Ok(event) => println!("event: {:?}", event),
+            Err(e) => println!("watch error: {:?}", e),
+        }
+    }
+
+    let mut watcher1 = notify::RecommendedWatcher::new(event_fn, Config::default())?;
+    // we will just use the same watcher kind again here
+    let mut watcher2 = notify::RecommendedWatcher::new(event_fn, Config::default())?;
+    watcher1.watch(Path::new("."), RecursiveMode::Recursive)?;
+    watcher2.watch(Path::new("."), RecursiveMode::Recursive)?;
+    Ok(())
+}
+
+fn main() -> Result<()> {
+    direct_init()?;
+    fallback_init()?;
+    Ok(())
+}

notify/src/lib.rs

@@ -46,6 +46,8 @@
 //! Docker on macos M1 [throws](https://github.com/notify-rs/notify/issues/423) `Function not implemented (os error 38)`.
 //! You have to manually use the [PollWatcher], as the native backend isn't available inside the emulation.
 //! 
+//! [recommended_watcher_fallback] works around this issue automatically.
+//! 
 //! ### MacOS, FSEvents and unowned files
 //! 
 //! Due to the inner security model of FSEvents (see [FileSystemEventSecurity](https://developer.apple.com/library/mac/documentation/Darwin/Conceptual/FSEvents_ProgGuide/FileSystemEventSecurity/FileSystemEventSecurity.html)),
@@ -282,6 +284,8 @@ pub enum WatcherKind {
     ReadDirectoryChangesWatcher,
     /// Fake watcher for testing
     NullWatcher,
+    /// If invoked on [WatcherFallback] created via [recommended_watcher_fallback]
+    UnknownFallback,
 }
 
 /// Type that can deliver file activity notifications
@@ -339,15 +343,23 @@ pub trait Watcher {
 }
 
 /// The recommended `Watcher` implementation for the current platform
+/// 
+/// Please use [recommended_watcher_fallback] if you want to be failsafe
 #[cfg(target_os = "linux")]
 pub type RecommendedWatcher = INotifyWatcher;
 /// The recommended `Watcher` implementation for the current platform
+/// 
+/// Please use [recommended_watcher_fallback] if you want to be failsafe
 #[cfg(all(target_os = "macos", not(feature = "macos_kqueue")))]
 pub type RecommendedWatcher = FsEventWatcher;
 /// The recommended `Watcher` implementation for the current platform
+/// 
+/// Please use [recommended_watcher_fallback] if you want to be failsafe
 #[cfg(target_os = "windows")]
 pub type RecommendedWatcher = ReadDirectoryChangesWatcher;
 /// The recommended `Watcher` implementation for the current platform
+/// 
+/// Please use [recommended_watcher_fallback] if you want to be failsafe
 #[cfg(any(
     target_os = "freebsd",
     target_os = "openbsd",
@@ -357,6 +369,8 @@ pub type RecommendedWatcher = ReadDirectoryChangesWatcher;
 ))]
 pub type RecommendedWatcher = KqueueWatcher;
 /// The recommended `Watcher` implementation for the current platform
+/// 
+/// Please use [recommended_watcher_fallback] if you want to be failsafe
 #[cfg(not(any(
     target_os = "linux",
     target_os = "macos",
@@ -370,16 +384,108 @@ pub type RecommendedWatcher = PollWatcher;
 
 /// Convenience method for creating the `RecommendedWatcher` for the current platform in
 /// _immediate_ mode.
+/// 
+/// Please note that unlike [recommended_watcher_fallback] this does not guard against unavailable APIs.
+///
+/// It is not more than calling `RecommendedWatcher::new`
 ///
-/// See [`Watcher::new_immediate`](trait.Watcher.html#tymethod.new_immediate).
+/// See [`Watcher::new`](trait.Watcher.html#tymethod.new).
+#[deprecated = "See recommended_watcher_fallback, does not guard against unavailable APIs"]
 pub fn recommended_watcher<F>(event_handler: F) -> Result<RecommendedWatcher>
 where
     F: EventHandler,
 {
     // All recommended watchers currently implement `new`, so just call that.
+    // TODO: v6 implement fallback, using recommended_watcher_fallback
     RecommendedWatcher::new(event_handler, Config::default())
 }
 
+/// Method for creating the `RecommendedWatcher` for the current platform or falling back.
+/// 
+/// Unlike [recommended_watcher] and [RecommendedWatcher] this falls back if the recommended API is not available.
+/// 
+/// Example use case is [#423](https://github.com/notify-rs/notify/issues/423) where Docker with QEMU on M1 chips does not expose the inotify OS API.
+///
+/// See also [`Watcher::new`](trait.Watcher.html#tymethod.new).
+pub fn recommended_watcher_fallback<F>(event_handler: F, config: Config) -> Result<WatcherFallback>
+where
+    F: EventHandler + Copy,
+{
+    // All recommended watchers currently implement `new`, so just call that.
+    match RecommendedWatcher::new(event_handler, config.clone()) {
+        Ok(v) => Ok(WatcherFallback::Native(v)),
+        Err(e) => {
+            match &e.kind {
+                #[allow(unused)]
+                ErrorKind::Io(io_error) => {
+                    #[cfg(target_os = "linux")]
+                    if io_error.raw_os_error() == Some(38) {
+                        return Ok(WatcherFallback::Fallback(PollWatcher::new(event_handler, config)?));
+                    }
+                },
+                _ => (),
+            }
+            return Err(e);
+        },
+    }
+}
+
+/// Wrapper for a fallback initialized watcher.
+/// 
+/// Can be used like a Watcher.
+/// 
+/// See [`recommended_watcher_fallback`](recommended_watcher_fallback)
+#[derive(Debug)]
+pub enum WatcherFallback {
+    /// Native watcher, no error occured
+    Native(RecommendedWatcher),
+    /// Fallback watcher, known platform issue occured
+    /// 
+    /// For example the Docker with Linux on MacOS M1 bug
+    Fallback(PollWatcher)
+}
+
+impl WatcherFallback {
+    /// Returns the watcher inside boxed
+    pub fn take_boxed(self) -> Box<dyn Watcher>{
+        match self {
+            WatcherFallback::Native(v) => Box::new(v),
+            WatcherFallback::Fallback(v) => Box::new(v),
+        }
+    }
+
+    /// Returns the [WatcherKind] used
+    pub fn kind(&self) -> WatcherKind {
+        match self {
+            // we can assume these kinds due to the way we initialize it
+            WatcherFallback::Native(_) => {
+                <RecommendedWatcher as Watcher>::kind()
+            },
+            WatcherFallback::Fallback(_) => WatcherKind::PollWatcher,
+        }
+    }
+}
+
+impl std::ops::Deref for WatcherFallback {
+    type Target = dyn Watcher;
+
+    fn deref(&self) -> &Self::Target {
+        match self {
+            WatcherFallback::Native(v) => v,
+            WatcherFallback::Fallback(v) => v,
+        }
+    }
+}
+
+impl std::ops::DerefMut for WatcherFallback {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        match self {
+            WatcherFallback::Native(v) => v,
+            WatcherFallback::Fallback(v) => v,
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

notify/src/windows.rs

@@ -498,7 +498,7 @@ impl ReadDirectoryChangesWatcher {
 }
 
 impl Watcher for ReadDirectoryChangesWatcher {
-    fn new<F: EventHandler>(event_handler: F, config: Config) -> Result<Self> {
+    fn new<F: EventHandler>(event_handler: F, _config: Config) -> Result<Self> {
         // create dummy channel for meta event
         // TODO: determine the original purpose of this - can we remove it?
         let (meta_tx, _) = unbounded();