Struct watchexec::Watchexec

pub struct Watchexec {
    pub config: Arc<Config>,
    /* private fields */
}

The main watchexec runtime.

All this really does is tie the pieces together in one convenient interface.

It creates the correct channels, spawns every available event sources, the action worker, the error hook, and provides an interface to change the runtime configuration during the runtime, inject synthetic events, and wait for graceful shutdown.

Fields

config: Arc<Config>

The configuration of this Watchexec instance.

Configuration can be changed at any time using the provided methods on Config.

Treat this field as readonly: replacing it with a different instance of Config will not do anything except potentially lose you access to the actual Watchexec config. In normal use you’ll have obtained Watchexec behind an Arc so that won’t be an issue.

Examples

Change the action handler:

let wx = Watchexec::default();
wx.config.on_action(|mut action| {
    if action.signals().next().is_some() {
        action.quit();
    }

    action
});

Set paths to be watched:

let wx = Watchexec::new(|mut action| {
    if action.signals().next().is_some() {
        action.quit();
    } else {
        for event in action.events.iter() {
            println!("{event:?}");
        }
    }

    action
}).unwrap();

wx.config.pathset(["."]);

Implementations

impl Watchexec

pub fn new( action_handler: impl Fn(ActionHandler) -> ActionHandler + Send + Sync + 'static ) -> Result<Arc<Self>, CriticalError>

Instantiates a new Watchexec runtime given an initial action handler.

Returns an Arc for convenience; use try_unwrap to get the value directly if needed, or use new_with_config.

Look at the Config documentation for more on the required action handler. Watchexec will subscribe to most signals sent to the process it runs in and send them, as Events, to the action handler. At minimum, you should check for interrupt/ctrl-c events and call action.quit() in your handler, otherwise hitting ctrl-c will do nothing.

pub fn new_async( action_handler: impl Fn(ActionHandler) -> Box<dyn Future<Output = ActionHandler> + Send + Sync> + Send + Sync + 'static ) -> Result<Arc<Self>, CriticalError>

Instantiates a new Watchexec runtime given an initial async action handler.

This is the same as new except the action handler is async.

pub fn with_config(config: Config) -> Result<Self, CriticalError>

Instantiates a new Watchexec runtime with a config.

This is generally not needed: the config can be changed after instantiation (before and after starting Watchexec with main()). The only time this should be used is to set the “unchangeable” configuration items for internal details like buffer sizes for queues, or to obtain Self unwrapped by an Arc like new() does.

pub async fn send_event( &self, event: Event, priority: Priority ) -> Result<(), CriticalError>

Inputs an Event directly.

This can be useful for testing, for custom event sources, or for one-off action triggers (for example, on start).

Hint: use Event::default() to send an empty event (which won’t be filtered).

pub fn main(&self) -> JoinHandle<Result<(), CriticalError>>

Start watchexec and obtain the handle to its main task.

This must only be called once.

Panics

Panics if called twice.

Trait Implementations

impl Debug for Watchexec

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

Formats the value using the given formatter.

impl Default for Watchexec

fn default() -> Self

Instantiate with default config.

Note that this will panic if the constructor errors.

Prefer calling new() instead.