method-side opt-out for unawaited_futures

[goderbauer]

Flutter has some API methods (like Navigator.push, AnimationController.forward, AnimationController.reverse) that return a Future, but in a lot of cases it is perfectly normal to just drop that Future on the floor. The unawaited_futures lint creates a lot of noise there, especially in tests.

It would be nice if there's an API-side opt-out for that lint where we can annotate the methods mentioned above with @unawaitedOk (or similar) and the lint would ignore it if a Future returned by those annotated methods is unawaited.

/cc @pq @Hixie @mit-mit @munificent @devoncarew

[srawlins]

Just to be clear, in other cases, you do want to wait for the Future, and access a contained value?

[goderbauer]

Yes. For example, if a route pushed via Navigator.push returns a value, you may want to await the Future to retrieve that value.

[pq]

There's some conceptual common ground with the open request for @CheckReturn or similar (see: #1888). It would be cool if we could find a synergetic solution.

[bwilkerson]

Flutter has some API methods (like Navigator.push, AnimationController.forward, AnimationController.reverse) that return a Future, but in a lot of cases it is perfectly normal to just drop that Future on the floor.

Is there a way that we can statically tell whether it's reasonable to drop the Future? I'm just wondering whether we can avoid both false positives (the status quo) and false negatives (the risk to allowing an annotation on these methods to stop all checking).

[Hixie]

It's ok to ignore a future when that future will never complete with an exception. It would be good for the lint to make that clear (e.g. @cannotThrow rather than @unawaitedOk).

[pq]

Annotation implementation in the SDK discussion going on here: dart-lang/sdk#46218.

[srawlins]

This is a duplicate of what #2513 eventually became, as of #419 (comment). #419 (comment) is a good summary.

[natebosch]

Do you have an example diff or diagnostics list from when this was explored in flutter/flutter or flutter/engine?

AnimationController.forward is not used in an async method in flutter/flutter. Navigator.push has a few uses in async methods, almost all were in tests and followed by await tester.pump(); or some variation. I had a hard time finding uses where an await would cause a problem, but there were a lot of non-async context uses to scan through and I didn't go through them all. Specific examples of where these APIs shouldn't be awaited would be helpful.

I'm surprised that the noise of unawaited for the few usages I saw out of the APIs mentioned is considered more of a problem than the risk of futures being silently unawaited today.

Is it intended that errors from these futures should be surfaced only by the zone error handler?

[goderbauer]

Turning on the lint on flutter/flutter reports almost 800 issues: https://gist.github.com/goderbauer/2e74e4299b82a7106dc47c012ca9e153.

I haven't checked all of these, but the ones I spot-checked where reported on AnimationController and Navigator APIs, whose futures can usually just be dropped on the floor. Awaiting these in tests unsurprisingly makes the test hang. So, telling people that they are missing an await here is somewhat misleading.

Is it intended that errors from these futures should be surfaced only by the zone error handler?

See Hixie's earlier comment in this thread. These futures are designed to never complete with an exception.

[natebosch]

These futures are designed to never complete with an exception.

In that case is there any concern with using .ignore() to make these explicitly ignored?

[goderbauer]

It's noisy, verbose, and somewhat annoying. If we already know that these can be safely ignored, why do our developers have to spent mental energy on the question of whether ignoring these is fine or not? Also, if developers make the wrong choice and accidentally await these (the lint is pushing them more in that direction then towards ignoring them) they'll have to spent more time debugging why their test is hanging.

[Hixie]

The other problem with .ignore() is that it's defined on an extension so when you're looking at code that uses it for the first time, it's very unobvious how to even look it up (e.g. the word "ignore" doesn't even appear on the docs for the Future class). In general I would strongly discourage any use of extensions for this reason.