From 7424e36e56dbda353364e6c6d856be3858f4b5f1 Mon Sep 17 00:00:00 2001 From: pantonshire Date: Sat, 19 Aug 2023 09:07:53 +0100 Subject: [PATCH] document new graceful shutdown behaviour --- src/lib.rs | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index cfae023..c5158ee 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -40,7 +40,8 @@ use std::{ /// # } /// ``` /// -/// When dropped, the debouncer will close the mpsc channel associated with it. +/// When dropped, the debouncer will gracefully shut down, closing the associated mpsc channel once +/// it has finished sending any remaining events. pub struct Debouncer { thread: Option>, // This is reference counted because the debouncer thread needs access to the controller, and @@ -57,11 +58,11 @@ where DebouncedEvent: Send + 'static, FoldFn: Fn(Option, RawEvent) -> DebouncedEvent, { - /// Create a new debouncer which deduplicates events it receives within the timeframe given by - /// `debounce_time`. The raw, un-debounced events can be sent to the debouncer with - /// [`Debouncer::debounce`](crate::Debouncer::debounce), and the resulting debounced events can - /// be received using the [`mpsc::Receiver`](std::sync::mpsc::Receiver) returned by this - /// function. + /// Create a new [`Debouncer`](Debouncer) which deduplicates events it receives within the + /// timeframe given by `debounce_time`. The raw, un-debounced events can be sent to the + /// debouncer with [`Debouncer::debounce`](crate::Debouncer::debounce), and the resulting + /// debounced events can be received using the [`mpsc::Receiver`](std::sync::mpsc::Receiver) + /// returned by this function. /// /// Events are deduplicated using the given `fold` function, which combines the current /// deduplicated event (an `Option`) with a new `RawEvent` to produce a new @@ -94,6 +95,9 @@ where /// # } /// ``` /// + /// When the returned [`Debouncer`](Debouncer) is dropped it will gracefully shut down, closing + /// the associated mpsc channel once it has finished sending any remaining events. + /// /// An [`io::Error`](std::io::Error) will be returned by this function if spawning the /// debouncer thread fails. pub fn new(debounce_time: Duration, fold: FoldFn)