Struct watchexec::config::Config

#[non_exhaustive]
pub struct Config {
    pub action_handler: ChangeableFn<ActionHandler, ActionReturn>,
    pub error_handler: ChangeableFn<ErrorHook, ()>,
    pub pathset: Changeable<Vec<WatchedPath>>,
    pub file_watcher: Changeable<Watcher>,
    pub keyboard_events: Changeable<bool>,
    pub throttle: Changeable<Duration>,
    pub filterer: ChangeableFilterer,
    pub error_channel_size: usize,
    pub event_channel_size: usize,
    /* private fields */
}

Configuration for Watchexec.

Almost every field is a Changeable, such that its value can be changed from a &self.

Fields are public for advanced use, but in most cases changes should be made through the methods provided: not only are they more convenient, each calls debug! on the new value, providing a quick insight into what your application sets.

The methods also set the “change signal” of the Config: this notifies some parts of Watchexec they should re-read the config. If you modify values via the fields directly, you should call signal_change() yourself. Note that this doesn’t mean that changing values without calling this will prevent Watchexec changing until it’s called: most parts of Watchexec take a “just-in-time” approach and read a config item immediately before it’s needed, every time it’s needed, and thus don’t need to listen for the change signal.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

action_handler: ChangeableFn<ActionHandler, ActionReturn>

The main handler to define: what to do when an action is triggered.

This handler is called with the [Action] environment, look at its doc for more detail.

If this handler is not provided, or does nothing, Watchexec in turn will do nothing, not even quit. Hence, you really need to provide a handler. This is enforced when using [Watchexec::new()], but not when using [Watchexec::default()].

It is possible to change the handler or any other configuration inside the previous handler. This and other handlers are fetched “just in time” when needed, so changes to handlers can appear instant, or may lag a little depending on lock contention, but a handler being called does not hold its lock. A handler changing while it’s being called doesn’t affect the run of a previous version of the handler: it will neither be stopped nor retried with the new code.

It is important for this handler to return quickly: avoid performing blocking work in it. This is true for all handlers, but especially for this one, as it will block the event loop and you’ll find that the internal event queues quickly fill up and it all grinds to a halt. Spawn threads or tasks, or use channels or other async primitives to communicate with your expensive code.

error_handler: ChangeableFn<ErrorHook, ()>

Runtime error handler.

This is run on every runtime error that occurs within Watchexec. The default handler is a no-op.

Examples

Set the error handler:

let mut config = Config::default();
config.on_error(|err: ErrorHook| {
    tracing::error!("{}", err.error);
});

Output a critical error (which will terminate Watchexec):

let mut config = Config::default();
config.on_error(|err: ErrorHook| {
    tracing::error!("{}", err.error);

    if matches!(err.error, RuntimeError::FsWatcher { .. }) {
        err.critical(CriticalError::External("fs watcher failed".into()));
    }
});

Elevate a runtime error to critical (will preserve the error information):

let mut config = Config::default();
config.on_error(|err: ErrorHook| {
    tracing::error!("{}", err.error);

    if matches!(err.error, RuntimeError::FsWatcher { .. }) {
           err.elevate();
    }
});

It is important for this to return quickly: avoid performing blocking work. Locking and writing to stdio is fine, but waiting on the network is a bad idea. Of course, an asynchronous log writer or separate UI thread is always a better idea than println! if have that ability.

pathset: Changeable<Vec<WatchedPath>>

The set of filesystem paths to be watched.

If this is non-empty, the filesystem event source is started and configured to provide events for these paths. If it becomes empty, the filesystem event source is shut down.

file_watcher: Changeable<Watcher>

The kind of filesystem watcher to be used.

keyboard_events: Changeable<bool>

Watch stdin and emit events when input comes in over the keyboard.

If this is true, the keyboard event source is started and configured to report when input is received on stdin. If it becomes false, the keyboard event source is shut down and stdin may flow to commands again.

Currently only EOF is watched for and emitted.

throttle: Changeable<Duration>

How long to wait for events to build up before executing an action.

This is sometimes called “debouncing.” We debounce on the trailing edge: an action is triggered only after that amount of time has passed since the first event in the cycle. The action is called with all the collected events in the cycle.

Default is 50ms.

filterer: ChangeableFilterer

The filterer implementation to use when filtering events.

The default is a no-op, which will always pass every event.

error_channel_size: usize

The buffer size of the channel which carries runtime errors.

The default (64) is usually fine. If you expect a much larger throughput of runtime errors, or if your error_handler is slow, adjusting this value may help.

This is unchangeable at runtime and must be set before Watchexec instantiation.

event_channel_size: usize

The buffer size of the channel which carries events.

The default (4096) is usually fine. If you expect a much larger throughput of events, adjusting this value may help.

This is unchangeable at runtime and must be set before Watchexec instantiation.

Implementations

impl Config

pub fn signal_change(&self) -> &Self

Signal that the configuration has changed.

This is called automatically by all other methods here, so most of the time calling this isn’t needed, but it can be useful for some advanced uses.

pub fn pathset<I, P>(&self, pathset: I) -> &Self

where I: IntoIterator<Item = P>, P: Into<WatchedPath>,

Set the pathset to be watched.

pub fn file_watcher(&self, watcher: Watcher) -> &Self

Set the file watcher type to use.

pub fn keyboard_events(&self, enable: bool) -> &Self

Enable keyboard/stdin event source.

pub fn throttle(&self, throttle: impl Into<Duration>) -> &Self

Set the throttle.

pub fn filterer(&self, filterer: impl Filterer + Send + Sync + 'static) -> &Self

Set the filterer implementation to use.

pub fn on_error( &self, handler: impl Fn(ErrorHook) + Send + Sync + 'static ) -> &Self

Set the runtime error handler.

pub fn on_action( &self, handler: impl Fn(ActionHandler) -> ActionHandler + Send + Sync + 'static ) -> &Self

Set the action handler.

pub fn on_action_async( &self, handler: impl Fn(ActionHandler) -> Box<dyn Future<Output = ActionHandler> + Send + Sync> + Send + Sync + 'static ) -> &Self

Set the action handler to a future-returning closure.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

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

Formats the value using the given formatter.

impl Default for Config

fn default() -> Self

Returns the “default value” for a type.