#[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 */
}
Expand description
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)§
This struct is marked as non-exhaustive
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§
source§impl Config
impl Config
sourcepub fn signal_change(&self) -> &Self
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.
sourcepub fn file_watcher(&self, watcher: Watcher) -> &Self
pub fn file_watcher(&self, watcher: Watcher) -> &Self
Set the file watcher type to use.
sourcepub fn keyboard_events(&self, enable: bool) -> &Self
pub fn keyboard_events(&self, enable: bool) -> &Self
Enable keyboard/stdin event source.
sourcepub fn filterer(&self, filterer: impl Filterer + Send + Sync + 'static) -> &Self
pub fn filterer(&self, filterer: impl Filterer + Send + Sync + 'static) -> &Self
Set the filterer implementation to use.
sourcepub fn on_error(
&self,
handler: impl Fn(ErrorHook) + Send + Sync + 'static
) -> &Self
pub fn on_error( &self, handler: impl Fn(ErrorHook) + Send + Sync + 'static ) -> &Self
Set the runtime error handler.
sourcepub fn on_action(
&self,
handler: impl Fn(ActionHandler) -> ActionHandler + Send + Sync + 'static
) -> &Self
pub fn on_action( &self, handler: impl Fn(ActionHandler) -> ActionHandler + Send + Sync + 'static ) -> &Self
Set the action handler.
sourcepub fn on_action_async(
&self,
handler: impl Fn(ActionHandler) -> Box<dyn Future<Output = ActionHandler> + Send + Sync> + Send + Sync + 'static
) -> &Self
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.