Add debouncer

[0xpr03]

Add debouncer back to v5.

Related #249

[0xpr03]

Open questions:

• Do we want to add multiple-receiver functionality?
• What is the priority for any/other events ?
• Do we allow much configuration in light of "Any" on invalid configurations overriding anything?
• Do we unify the debouncer and configuration into one thing ? Do we want to split it up into separate APIs?
• Do we want to spawn another thread for timing? Otherwise we'll need more redesign.
• What exactly would be the best debounced event kind? I currently leave out AnyMap and simply use the first t of the EventKind(t) provided, ignoring in-depth details such as the exact ModifyKind, rendering the actual modify events ModifyKind useless.
• The original API accepted a simple Receiver, is there any use case for accepting a sender instead of spawning the watcher internally and only returning a receiver?

[0xpr03]

Another I just realized: We need an idea how we handle configuration changes for debouncer and immediate watchers. Currently we don't care at all. Historically every debouncer init was implemented at the specific notify modules (inotify, fsevent..).

What I realized: we don't actually implement any of the current config options. Or am I wrong ? Searching for PreciseEvents doesn't emit one hit across any of the specific implementations. Also from all the config options exactly one is relevant to the specific implementations of the immediate watchers: PreciseEvents, everything else is related to the debouncer. Thus the whole ".config()" operation is nearly irrelevant for immediate watchers.

cc @JohnTitor

[passcod]

Notes from implementing the watchexec 2.0 debouncer:

• An important consideration in watchexec was that the filtering would apply before/during debouncing. So events are discarded if filtered out, and end up not affecting the debouncing. To me that's the biggest hurdle this module would have: if end user wants to filter events at all it's more correct to do it during debounce, but providing an interface for that within the module is... too big a scope I think

• Looking through notify while I implemented-- I don't think config is really used at all, and I'm dubious about notice and precise events now. I was trying to scope notify a lot larger, which I think made the design suffer. But I could be misremembering / not recalling concerns, idk.

• The main advantages of a notify built-in debouncer imo are:

  • to provide a useful interface for the common/naive case
  • to resolve renames

  That second one is useful all the time, the first less so. Unsure if they could be decoupled in some way.

• Initially I recorded times/instants for events received/emitted, but I discarded that pretty fast. However, it's probably that I don't see the need in watchexec rather than it not being useful generally.

• Notify's debouncer historically groups by major event kind and aggregates into a synthetic type; watchexec's doesn't. There was some discussion on here about the common usecase being "did something change" rather than "did something get added/removed/modified"; that's what I embraced. Watchexec's debouncer output is a Vec<Event>, basically.

For reference, algorithm I implemented (simplified):

let throttle: Duration = unimplemented!("input: debouncer interval");
let mut last = Instant::now();
let mut set = Vec::new();

loop {
    let maxtime = if set.is_empty() {
        Duration::from_secs(u64::MAX)
    } else {
        throttle.saturating_sub(last.elapsed())
    };

    if maxtime.is_zero() {
        if set.is_empty() {
            last = Instant::now();
            continue;
        } else {
            // we're out of the debouncing
        }
    } else {
        match timeout(maxtime, events.recv()).await {
            Err(_timeout) => continue,
            Ok(None) => break, // exit
            Ok(Some(event)) => {
                // filtering applied here, if fail reset loop

                if set.is_empty() {
                    last = Instant::now();
                }

                set.push(event);

                if last.elapsed() < throttle {
                    continue;
                }
            }
        }
    }

    // we're out of the debouncing, pass event set to consumer
    last = Instant::now();
    let pass_this = set.drain(..).collect();
}

[IWANABETHATGUY]

I am curious when will this be merged ?

[0xpr03]

Once I've got time to fully undertake this as there is a lot I want to get right or at least decide actively to not include it, as you can read above. Which due to private things going on could take until march next year. I consider v4 to be pretty stable, so feel free to use that one.

[0xpr03]

This is the tiniest debouncer I could imagine being useful. Only Any events are delivered and AnyContinuous for ongoing events past the timeout.

Things I don't like:

• you can't change the tick rate
• you can't change the timeout
• you can't provide the backend

[0xpr03]

The real problem with all of these three is how we pass the configuration stuff back and forth. User -> backend (config), User -> debouncer (config), backend -> debouncer (events, errors), debouncer -> User (events, errors)

[JohnTitor]

I'm not too familiar with it but the implementation looks great to me with a nit!

[JohnTitor]

nit: I'd like to manage this value as const and declare it on the module scope.

[0xpr03]

understandable, had a moment of wrangling with myself whether I'd want that as top module declaration

[0xpr03]

This got a little bit bigger now. Fixing the audit issues and decoupling the debouncer from notify core.

[0xpr03]

As good as finished.
One open point is how I could enable custom watcher options (see pollwatcher) with this system ? Currently I can't think of a good combination. The optional crossbeam feature should be enhanced when we land an additional feature in notify itself to allow disabling crossbeam entirely for tokio compatibility.