Add method for native watcher initialization with fallback

[0xpr03]

Ads a new method for initializing the recommended watcher and falling back to pollwatcher on failure to do so

Fixes #423

[0xpr03]

This is a draft because:

1. I'd like to also change the recommended_watcher function to just call the new one, giving it more value, but would have to change its result value. Not sure if we can do that semver compatible (or just ignore it).
2. I've opted for an enum type instead of Box<dyn Watcher>, I could also imagine using that.
3. I've only handled the specific Function not implemented (os error 38) when running on docker in M1 MacOS  #423 error. We could also fallback for any error.
4. Do we want to report the original error with the fallback ? Add some additional error kind "unavailable API" to at least report it?
5. This requires EventHandler to be declared either Copy or Clone for this fallback function. Even more of a SemVer break for recommended_watcher

Todo:

• Add docs entry in the issue for using that
• Change example to use the new function
• allow debouncer init with fallback (maybe add an easier init)

CC @samuelcolvin as possible consumer

[JohnTitor]

1. I'd like to also change the recommended_watcher function to just call the new one, giving it more value, but would have to change its result value. Not sure if we can do that semver compatible (or just ignore it).

I'd call it a breaking change if it changes behavior.

2. I've opted for an enum type instead of Box<dyn Watcher>, I could also imagine using that.

I think it's totally fine while we have take_boxed.

3. I've only handled the specific Function not implemented (os error 38) when running on docker in M1 MacOS #423 error. We could also fallback for any error.

These could come later :)

4. Do we want to report the original error with the fallback ? Add some additional error kind "unavailable API" to at least report it?

I don't have a strong opinion on that, maybe we could prepare an optional value?

5. This requires EventHandler to be declared either Copy or Clone for this fallback function. Even more of a SemVer break for recommended_watcher

Hmm, that sounds like a rather difficult issue and I cannot prepare a solution for that soon (I'm now fixing my dev env and cannot check your code deeply).

[samuelcolvin]

broadly seems fine to me, I'll probably stick with that I have now in watchfiles though since it's working well.

[samuelcolvin]

Is there a documented meaning to 38 or indeed other codes somewhere? I suspect we should fallback in more cases but I have no idea how to find out which ones should be an error and which should fallback.

[0xpr03]

Hm, here is the manpage though I prefer this list
Problem is that this does not tell us which of these could be emitted by our specific syscall.

[samuelcolvin]

personally I would prefer that this implemented watch. Is that very verbose/difficult?

[0xpr03]

that's a very good idea! and it would make the enum more worthwhile (because otherwise I don't actually see much of a value over directly boxing it, except for claiming the allocation-free throne, while not being useful at all)

[0xpr03]

Ok I tried this.. And it gets awkward.

• We can't implement Watcher::new due to missing Copy/Clone on event_handler.
• We can't implement a real kind(), as we don't have access to self. This kind of API is specifically not designed for runtime-selected watchers it seems. (V6 incoming.. ) We could still implement the functions without the trait, or leave them unimplemented!() for the new and the additional watcher-kind as in my new code.

Edit: But we can implement Deref and DerefMut, allowing direct Watcher::* access, but also kind(&self), which isn't the Trait, but at least gives the functionality.

[0xpr03]

Please review again, the addition of Deref/DerefMut allows direct access to the watcher in our enum, making the whole stack allocation worthwhile, such that boxing is not required. Example

Open Questions:

• Do we deprecate recommended_watcher() to reflect that it's kind of unhelpful as a function (in light of RecommendedWatcher) ?
• Do we migrate all examples (except for one) and the docs to recommend using recommended_watcher_fallback over RecommendedWatcher ? Technically it is the only way which we can get to actually work on all systems (and can work around future issues). In a way comptime-selection was fun while it lasted. On the other hand a lot of people don't seem to care about the specific issue on M1 + Docker (you can also say people should not expect such weird emulator setups to work), but I don't see a drawback for people already using RecommendedWatcher to migrate to the dynamic approach.
• Bikeshed: Is there a better name than recommended_watcher_fallback ? It's kinda long when for normal users I'd say it is the recommended way.
• I have no good answer to the copy/clone requirement of the fallback logic. We need it for recommended_watcher_fallback, so it's an additional requirement. We may just leave it as that.

[juliusl]

Bikeshed: Is there a better name than recommended_watcher_fallback ? It's kinda long when for normal users I'd say it is the recommended way. @0xpr03

How about ensure_watcher? From my experience, ensure has a stronger implication that a resource will be obtained.