Improve docs

Author: dfaust

file-id/src/lib.rs

@@ -1,20 +1,19 @@
-/// A utility to read file IDs.
-///
-/// Modern file systems assign a unique ID to each file. On Linux and MacOS it is called an `inode number`, on Windows it is called `file index`.
-/// Together with the `device id`, a file can be identified uniquely on a device at a given time.
-///
-/// Keep in mind though, that IDs may be re-used at some point.
-///
-/// ## Example
-///
-/// ```rust
-/// # let file = tempfile::NamedTempFile::new().unwrap();
-/// # let path = file.path();
-///
-/// let file_id = file_id::get_file_id(path).unwrap();
-///
-/// println!("{file_id:?}");
-/// ```
+//! A utility to read file IDs that are unique on a given device.
+//!
+//! Modern file systems assign a unique ID to each file. On Linux and MacOS it is called an `inode number`, on Windows it is called a `file index`.
+//! Together with the `device id`, a file can be identified uniquely on a device at a given time.
+//!
+//! Keep in mind though, that IDs may be re-used at some point.
+//!
+//! ## Example
+//!
+//! ```rust
+//! let file = tempfile::NamedTempFile::new().unwrap();
+//!
+//! let file_id = file_id::get_file_id(file.path()).unwrap();
+//!
+//! println!("{file_id:?}");
+//! ```
 use std::{fs, io, path::Path};
 
 #[cfg(feature = "serde")]

notify-debouncer-refined/src/cache.rs

@@ -7,23 +7,52 @@ use file_id::{get_file_id, FileId};
 use notify::RecursiveMode;
 use walkdir::WalkDir;
 
+/// The interface of a file ID cache.
+/// 
+/// This trait can be implemented for an existing cache, if it already holds `FileId`s.
 pub trait FileIdCache {
+    /// Get a `FileId` from the cache for a given `path`.
+    /// 
+    /// If the path is not cached, `None` should be returned and there should not be any attempt to read the file ID from disk.
     fn cached_file_id(&self, path: &Path) -> Option<&FileId>;
 
+    /// Add a new path to the cache or update its value.
+    /// 
+    /// This will be called if a new file or directory is created or if an existing file is overridden.
     fn add_path(&mut self, path: &Path);
 
+    /// Remove a path from the cache.
+    /// 
+    /// This will be called if a file or directory is deleted.
     fn remove_path(&mut self, path: &Path);
 
+    /// Re-scan all paths.
+    /// 
+    /// This will be called if the notification back-end has dropped events.
     fn rescan(&mut self);
 }
 
+/// A cache to hold the file system IDs of all watched files.
+///
+/// The file ID cache uses unique file IDs provided by the file system and is used to stich together
+/// rename events in case the notification back-end doesn't emit rename cookies.
 #[derive(Debug, Clone, Default)]
-pub struct PathCache {
+pub struct FileIdMap {
     paths: HashMap<PathBuf, FileId>,
     roots: Vec<(PathBuf, RecursiveMode)>,
 }
 
-impl PathCache {
+impl FileIdMap {
+    /// Construct an empty cache.
+    pub fn new() -> Self {
+        Default::default()
+    }
+
+    /// Add a path to the cache.
+    /// 
+    /// If `recursive_mode` is `Recursive`, all children will be added to the cache as well
+    /// and all paths will be kept up-to-date in case of changes like new files being added,
+    /// files being removed or renamed.
     pub fn add_root(&mut self, path: impl Into<PathBuf>, recursive_mode: RecursiveMode) {
         let path = path.into();
 
@@ -32,6 +61,9 @@ impl PathCache {
         self.add_path(&path);
     }
 
+    /// Remove a path form the cache.
+    /// 
+    /// If the path was added with `Recursive` mode, all children will also be removed from the cache.
     pub fn remove_root(&mut self, path: impl AsRef<Path>) {
         self.roots.retain(|(root, _)| !root.starts_with(&path));
 
@@ -47,7 +79,7 @@ impl PathCache {
     }
 }
 
-impl FileIdCache for PathCache {
+impl FileIdCache for FileIdMap {
     fn cached_file_id(&self, path: &Path) -> Option<&FileId> {
         self.paths.get(path)
     }
@@ -90,6 +122,9 @@ impl FileIdCache for PathCache {
     }
 }
 
+/// An implementation of the `FileIdCache` trait that doesn't hold any data.
+///
+/// This pseudo cache can be used to disable the file tracking using file system IDs.
 pub struct NoCache;
 
 impl FileIdCache for NoCache {

notify-debouncer-refined/src/lib.rs

@@ -1,16 +1,25 @@
-//! Debouncer for notify
+//! A debouncer for [notify] that is optimized for ease of use.
+//!
+//! * Only emits a single `Rename` event if the rename `From` and `To` events can be matched
+//! * Merges multiple `Rename` events
+//! * Optionally keeps track of the file system IDs all files and stiches rename events together (FSevents, Windows)
+//! * Emits only one `Remove` event when deleting a directory (inotify)
+//! * Doesn't emit duplicate create events
+//! * Doesn't emit `Modify` events after a `Create` event
 //!
 //! # Installation
 //!
 //! ```toml
 //! [dependencies]
-//! notify-debouncer-easy = "0.2.0"
+//! notify-debouncer-refined = "0.1.0"
 //! ```
+//!
 //! In case you want to select specific features of notify,
 //! specify notify as dependency explicitely in your dependencies.
 //! Otherwise you can just use the re-export of notify from debouncer-easy.
+//!
 //! ```toml
-//! notify-debouncer-easy = "0.2.0"
+//! notify-debouncer-refined = "0.1.0"
 //! notify = { version = "..", features = [".."] }
 //! ```
 //!  
@@ -21,20 +30,23 @@
 //! # use std::time::Duration;
 //! use notify_debouncer_refined::{notify::*, new_debouncer, DebounceEventResult};
 //!
-//! # fn main() {
-//!     // Select recommended watcher for debouncer.
-//!     // Using a callback here, could also be a channel.
-//!     let mut debouncer = new_debouncer(Duration::from_secs(2), None, |result: DebounceEventResult| {
-//!         match result {
-//!             Ok(events) => events.iter().for_each(|event| println!("{event:?}")),
-//!             Err(errors) => errors.iter().for_each(|error| println!("{error:?}")),
-//!         }
-//!     }).unwrap();
+//! // Select recommended watcher for debouncer.
+//! // Using a callback here, could also be a channel.
+//! let mut debouncer = new_debouncer(Duration::from_secs(2), None, |result: DebounceEventResult| {
+//!     match result {
+//!         Ok(events) => events.iter().for_each(|event| println!("{event:?}")),
+//!         Err(errors) => errors.iter().for_each(|error| println!("{error:?}")),
+//!     }
+//! }).unwrap();
 //!
-//!     // Add a path to be watched. All files and directories at that path and
-//!     // below will be monitored for changes.
-//!     debouncer.watcher().watch(Path::new("."), RecursiveMode::Recursive).unwrap();
-//! # }
+//! // Add a path to be watched. All files and directories at that path and
+//! // below will be monitored for changes.
+//! debouncer.watcher().watch(Path::new("."), RecursiveMode::Recursive).unwrap();
+//!
+//! // Add the same path to the file ID cache. The cache uses unique file IDs
+//! // provided by the file system and is used to stich together rename events
+//! // in case the notification back-end doesn't emit rename cookies.
+//! debouncer.cache().add_root(Path::new("."), RecursiveMode::Recursive);
 //! ```
 //!
 //! # Features
@@ -59,7 +71,7 @@ use std::{
     time::Duration,
 };
 
-pub use cache::{FileIdCache, PathCache};
+pub use cache::{FileIdCache, FileIdMap, NoCache};
 
 pub use file_id;
 pub use notify;
@@ -166,7 +178,6 @@ impl Queue {
     }
 }
 
-#[derive(Default)]
 pub(crate) struct DebounceDataInner<T> {
     queues: HashMap<PathBuf, Queue>,
     cache: T,
@@ -177,6 +188,17 @@ pub(crate) struct DebounceDataInner<T> {
 }
 
 impl<T: FileIdCache> DebounceDataInner<T> {
+    pub(crate) fn new(cache: T, timeout: Duration) -> Self {
+        Self {
+            queues: HashMap::new(),
+            cache,
+            rename_event: None,
+            rescan_event: None,
+            errors: Vec::new(),
+            timeout,
+        }
+    }
+
     /// Retrieve a vec of debounced events, removing them if not continuous
     pub fn debounced_events(&mut self) -> Vec<DebouncedEvent> {
         let now = Instant::now();
@@ -458,14 +480,6 @@ impl<T: FileIdCache> DebounceDataInner<T> {
         let path = &event.paths[0];
 
         if let Some(queue) = self.queues.get_mut(path) {
-            // if matches!(
-            //     event.kind,
-            //     EventKind::Modify(ModifyKind::Data(_) | ModifyKind::Metadata(_))
-            //         | EventKind::Access(_)
-            // ) {
-            //     queue.events.retain(|(_, e)| e.kind != event.kind);
-            // }
-
             // skip duplicate create events and modifications right after creation
             if match event.kind {
                 EventKind::Modify(ModifyKind::Data(_) | ModifyKind::Metadata(_))
@@ -485,7 +499,7 @@ impl<T: FileIdCache> DebounceDataInner<T> {
     }
 }
 
-/// Debouncer guard, stops the debouncer on drop
+/// Debouncer guard, stops the debouncer on drop.
 pub struct Debouncer<T: Watcher, C: FileIdCache> {
     watcher: T,
     debouncer_thread: Option<std::thread::JoinHandle<()>>,
@@ -531,21 +545,17 @@ impl<T: Watcher, C: FileIdCache> Drop for Debouncer<T, C> {
 
 /// Creates a new debounced watcher with custom configuration.
 ///
-/// Timeout is the amount of time after which a debounced event is emitted or a continuous event is send, if there still are events incoming for the specific path.
+/// Timeout is the amount of time after which a debounced event is emitted.
 ///
-/// If tick_rate is None, notify will select a tick rate that is less than the provided timeout.
-pub fn new_debouncer_opt<
-    F: DebounceEventHandler,
-    T: Watcher,
-    C: FileIdCache + Default + Send + 'static,
->(
+/// If tick_rate is None, notify will select a tick rate that is 1/4 of the provided timeout.
+pub fn new_debouncer_opt<F: DebounceEventHandler, T: Watcher, C: FileIdCache + Send + 'static>(
     timeout: Duration,
     tick_rate: Option<Duration>,
     mut event_handler: F,
+    file_id_cache: C,
     config: notify::Config,
 ) -> Result<Debouncer<T, C>, Error> {
-    let data = DebounceData::<C>::default();
-
+    let data = Arc::new(Mutex::new(DebounceDataInner::new(file_id_cache, timeout)));
     let stop = Arc::new(AtomicBool::new(false));
 
     let tick_div = 4;
@@ -567,11 +577,6 @@ pub fn new_debouncer_opt<
         })?,
     };
 
-    {
-        let mut data_w = data.lock();
-        data_w.timeout = timeout;
-    }
-
     let data_c = data.clone();
     let stop_c = stop.clone();
     let thread = std::thread::Builder::new()
@@ -620,20 +625,21 @@ pub fn new_debouncer_opt<
     Ok(guard)
 }
 
-/// Short function to create a new debounced watcher with the recommended debouncer.
+/// Short function to create a new debounced watcher with the recommended debouncer and the built-in file ID cache.
 ///
-/// Timeout is the amount of time after which a debounced event is emitted or a continuous event is send, if there still are events incoming for the specific path.
+/// Timeout is the amount of time after which a debounced event is emitted.
 ///
-/// If tick_rate is None, notify will select a tick rate that is less than the provided timeout.
+/// If tick_rate is None, notify will select a tick rate that is 1/4 of the provided timeout.
 pub fn new_debouncer<F: DebounceEventHandler>(
     timeout: Duration,
     tick_rate: Option<Duration>,
     event_handler: F,
-) -> Result<Debouncer<RecommendedWatcher, PathCache>, Error> {
-    new_debouncer_opt::<F, RecommendedWatcher, PathCache>(
+) -> Result<Debouncer<RecommendedWatcher, FileIdMap>, Error> {
+    new_debouncer_opt::<F, RecommendedWatcher, FileIdMap>(
         timeout,
         tick_rate,
         event_handler,
+        FileIdMap::new(),
         notify::Config::default(),
     )
 }