Struct FolderWatch 

pub struct FolderWatch { /* private fields */ }

Watches folders for changes the operating system reports, and never polls.

The watch is not recursive: a folder’s own entries are watched, not what happens deeper down. That matches a file tree, which only has to know about the folders it shows open.

The watch is owned by the application, which adds and removes folders as the user opens and closes them. The waiting happens elsewhere: changes gives a handle whose FolderChanges::next blocks, sleeping in the kernel, until something changes. Run it in a Command::perform and start it again when its message arrives. Dropping the watch wakes a waiting next, which then answers an empty list.

let mut watch = FolderWatch::new()?;
watch.watch(std::path::Path::new("/home/me/project"))?;
let changes = watch.changes();
// Inside a `Command::perform`:
for change in changes.next() {
    println!("{} changed: {:?}", change.folder.display(), change.kind);
}

Only Linux has this watch so far, through inotify. On every other platform FolderWatch::new returns an error of kind io::ErrorKind::Unsupported, and the application keeps rereading at the moments it chooses (after its own changes, on return to a screen, on a “refresh” key). macOS and Windows have their own event sources, but this framework reaches none of them without unsafe or a large dependency.

Implementations

impl FolderWatch

pub fn new() -> Result<Self>

A watch with no folders yet.

Errors

Returns the system’s error when no watch can be made (too many open watches for this user, for example), and io::ErrorKind::Unsupported on a platform other than Linux.

pub fn watch(&mut self, folder: &Path) -> Result<()>

Starts watching the entries of folder. Watching a folder that is already watched does nothing.

Errors

Returns the error when folder is missing or is not a folder, and an error of kind io::ErrorKind::QuotaExceeded when the system’s limit on watches (fs.inotify.max_user_watches on Linux) is reached. Either way the application can go on without live changes for that folder.

pub fn unwatch(&mut self, folder: &Path)

Stops watching folder. A folder that is not watched, or that is FolderChangeKind::Gone, is left alone.

pub fn changes(&self) -> FolderChanges

The handle that waits for this watch’s changes.

Trait Implementations

impl Debug for FolderWatch

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for FolderWatch

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.