Async File System Watching

In this lesson, you will learn how to bridge OS-level file system events into an asynchronous reactor to trigger non-blocking logic.

The Bridge: From Interrupts to Futures

Most operating systems provide high-performance APIs (like inotify on Linux, FSEvents on macOS, or ReadDirectoryChangesW on Windows) that send signals when a file or directory changes. Because these are blocking or polling-based by nature, integrating them into an async runtime requires converting these OS signals into a Stream.

The core architectural challenge is "lifting" a blocking callback or event loop into the poll mechanism of the Future trait. To do this, we use a channel-based bridge. Your reactor runs a dedicated thread—often managed by a background task—that listens to the OS kernel. When an event occurs, it pushes the event into a mpsc (multi-producer, single-consumer) channel.

Implementation Pattern

By wrapping this channel in an async stream, your application can consume file events without blocking the executor threads:

use tokio::sync::mpsc;
use tokio_stream::wrappers::ReceiverStream;

// This runs on a dedicated background thread or a blocking task
fn watch_path(tx: mpsc::Sender<Event>) {
    let mut watcher = notify::recommended_watcher(move |res| {
        if let Ok(event) = res {
            let _ = tx.blocking_send(event);
        }
    }).unwrap();
    // Watch logic here...
}

// In your async context
let (tx, rx) = mpsc::channel(100);
std::thread::spawn(move || watch_path(tx));

let mut stream = ReceiverStream::new(rx);
while let Some(event) = stream.next().await {
    process_event(event).await; // Non-blocking reaction
}

By decoupling the OS-level watcher from the reactor through a channel, you ensure that the high-latency (or potentially blocking) nature of OS file notifications does not stall your executor's thread pool. The ReceiverStream effectively converts the push-based notification from the OS into a pull-based Stream that the async runtime can poll efficiently. When no events are present, the task remains suspended, consuming zero CPU until the kernel wakes it via the channel sender.

Key Takeaway: Decouple OS notification threads from your async reactor using a channel-based bridge to transform kernel events into non-blocking streams.