Struct Watcher 

pub struct Watcher { /* private fields */ }

Watches one or more resources

These can be created with Watcher::new(). You can create as many Watchers as you want, and they can watch as many objects as you wish. The objects do not need to be the same type.

Each Watcher is backed by a kqueue(2) queue. These resources are freed on the Watchers destruction. If the destructor cannot run for whatever reason, the underlying kernel object will be leaked.

Files and file descriptors given to the Watcher are presumed to be owned by the Watcher, and will be closed when they’re removed from the Watcher or on Drop. In a future version, the API will make this explicit via OwnedFds

Implementations

impl Watcher

pub fn new() -> Result<Watcher>

Creates a new Watcher

Creates a brand new Watcher with KqueueOpts::default(). Will return an io::Error if creation fails.

pub fn disable_clears(&mut self) -> &mut Self

Disables the clear flag on a Watcher. New events will no longer be added with the EV_CLEAR flag on watch.

pub fn add_pid( &mut self, pid: pid_t, filter: EventFilter, flags: FilterFlag, ) -> Result<()>

Adds a pid to the Watcher to be watched

pub fn add_filename<P: AsRef<Path>>( &mut self, filename: P, filter: EventFilter, flags: FilterFlag, ) -> Result<()>

Adds a file by filename to be watched

NB: kqueue(2) is an fd-based API. If you add a filename with add_filename, internally we open it and pass the file descriptor to kqueue(2). If the file is moved or deleted, and a new file is created with the same name, you will not receive new events for it without calling add_filename again.

TODO: Adding new files requires calling Watcher.watch again

pub fn add_fd( &mut self, fd: RawFd, filter: EventFilter, flags: FilterFlag, ) -> Result<()>

Adds a descriptor to a Watcher. This or add_file is the preferred way to watch a file

TODO: Adding new files requires calling Watcher.watch again

pub fn add_file( &mut self, file: &File, filter: EventFilter, flags: FilterFlag, ) -> Result<()>

Adds a File to a Watcher. This, or add_fd is the preferred way to watch a file

TODO: Adding new files requires calling Watcher.watch again

pub fn remove_pid(&mut self, pid: pid_t, filter: EventFilter) -> Result<()>

Removes a pid from a Watcher

pub fn remove_filename<P: AsRef<Path> + Debug>( &mut self, filename: P, filter: EventFilter, ) -> Result<()>

Removes a filename from a Watcher.

NB: This matches the filename that this item was initially added under. If a file has been moved, it will not be removable by the new name.

pub fn remove_fd(&mut self, fd: RawFd, filter: EventFilter) -> Result<()>

Removes an fd from a Watcher. This closes the fd.

pub fn remove_file(&mut self, file: &File, filter: EventFilter) -> Result<()>

Removes a File from a Watcher

pub fn watch(&mut self) -> Result<()>

Starts watching for events from kqueue(2). This function needs to be called before Watcher.iter() or Watcher.poll() to actually start listening for events.

pub fn poll(&self, timeout: Option<Duration>) -> Option<Event>

Polls for a new event, with an optional timeout. If no timeout is passed, then it will return immediately.

pub fn poll_forever(&self, timeout: Option<Duration>) -> Option<Event>

Polls for a new event, with an optional timeout. If no timeout is passed, then it will block until an event is received.

pub fn iter(&self) -> EventIter<'_>

Creates an iterator that iterates over the queue. This iterator will block until a new event is received.

Trait Implementations

impl AsRawFd for Watcher

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Watcher

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

Formats the value using the given formatter.

impl Drop for Watcher

fn drop(&mut self)

Executes the destructor for this type.