From 705336018748594fe2a084ee1a999f6337af9ec6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fe=CC=81lix=20Saparelli?= <felix@passcod.name>
Date: Tue, 17 Aug 2021 01:37:01 +1200
Subject: [PATCH] Clarify fs worker usage

---
 Cargo.lock         |  1 +
 lib/Cargo.toml     |  1 +
 lib/examples/fs.rs | 27 +++++++++++++++++++++------
 lib/src/fs.rs      |  4 +++-
 4 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 59ffc1a..dfd0c8d 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2055,6 +2055,7 @@ name = "watchexec"
 version = "1.17.1"
 dependencies = [
  "chrono",
+ "color-eyre",
  "dunce",
  "miette",
  "notify 5.0.0-pre.11",
diff --git a/lib/Cargo.toml b/lib/Cargo.toml
index 404c0ca..4a5674c 100644
--- a/lib/Cargo.toml
+++ b/lib/Cargo.toml
@@ -27,5 +27,6 @@ version = "1.10.0"
 features = ["full"]
 
 [dev-dependencies]
+color-eyre = "0.5.11"
 tracing-subscriber = "0.2.19"
 
diff --git a/lib/examples/fs.rs b/lib/examples/fs.rs
index 31d7779..ea4d488 100644
--- a/lib/examples/fs.rs
+++ b/lib/examples/fs.rs
@@ -1,11 +1,17 @@
-use std::error::Error;
+use std::time::Duration;
 
-use tokio::sync::{mpsc, watch};
+use tokio::{
+	sync::{mpsc, watch},
+	time::sleep,
+};
 use watchexec::fs;
 
+// Run with: `env RUST_LOG=debug cargo run --example fs`,
+// then touch some files within the first 15 seconds, and afterwards.
 #[tokio::main]
-async fn main() -> Result<(), Box<dyn Error>> {
+async fn main() -> color_eyre::eyre::Result<()> {
 	tracing_subscriber::fmt::init();
+	color_eyre::install()?;
 
 	let (ev_s, mut ev_r) = mpsc::channel(1024);
 	let (er_s, mut er_r) = mpsc::channel(64);
@@ -13,21 +19,30 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
 	let mut wkd = fs::WorkingData::default();
 	wkd.pathset = vec![".".into()];
-	wd_s.send(wkd)?;
+	wd_s.send(wkd.clone())?;
 
 	tokio::spawn(async move {
 		while let Some(e) = ev_r.recv().await {
-			println!("event: {:?}", e);
+			tracing::info!("event: {:?}", e);
 		}
 	});
 
 	tokio::spawn(async move {
 		while let Some(e) = er_r.recv().await {
-			println!("error: {}", e);
+			tracing::error!("error: {}", e);
 		}
 	});
 
+	let wd_sh = tokio::spawn(async move {
+		sleep(Duration::from_secs(15)).await;
+		wkd.pathset = Vec::new();
+		tracing::info!("turning off fs watcher without stopping it");
+		wd_s.send(wkd).unwrap();
+		wd_s
+	});
+
 	fs::worker(wd_r, er_s, ev_s).await?;
+	wd_sh.await?;
 
 	Ok(())
 }
diff --git a/lib/src/fs.rs b/lib/src/fs.rs
index 5e61b3a..8054eea 100644
--- a/lib/src/fs.rs
+++ b/lib/src/fs.rs
@@ -57,7 +57,8 @@ pub struct WorkingData {
 /// While you can run several, you should only have one.
 ///
 /// This only does a bare minimum of setup; to actually start the work, you need to set a non-empty pathset on the
-/// [`WorkingData`] with the [`watch`] channel, and send a notification.
+/// [`WorkingData`] with the [`watch`] channel, and send a notification. Take care _not_ to drop the watch sender:
+/// this will cause the worker to stop gracefully, which may not be what was expected.
 ///
 /// # Examples
 ///
@@ -183,6 +184,7 @@ pub async fn worker(
 		}
 	}
 
+	debug!("ending file watcher");
 	Ok(())
 }
 fn process_event(