Choose the type argument for the future returned from an invocation of an async function

[eernstg]

When an async function is invoked, a fresh instance of Future<T> for some T is returned at some point, and there is no user-written code which creates that future so the choice of T is not made by a developer. The specification currently leaves it unspecified which value to use for T:

If f is marked async (9), then a fresh instance (10.6.1) o implementing
the built-in class Future is associated with the invocation. Then the body
of f is executed until it either suspends or completes, at which point o is
returned.

This issue serves to recommend that we specify this type argument explicitly.

To get started we may consider a couple of loose ideas: Future<T> f() async {...} should return an instance of Future<T>. void f() async {...} should return an instance of Future<void>. FutureOr<T> f() async {...} should probably return an instance of Future<T>. Etc.

[eernstg]

@lrhn, @leafpetersen do you agree that we should extend the specification to make an explicit choice in this area? I suppose it will fit as an update of dartLangSpec.tex directly, with no intervening feature specification.

[leafpetersen]

Yes, we should specify this. I think the right answer is that the returned value should be a Future<flatten(returnType)>.

[eernstg]

Right, that would be as follows (declared return type --> dynamic type of returned Future):

void --> Future<void>
dynamic --> Future<dynamic>
Object --> Future<Object>
Future<T> --> Future<T>, for all T
FutureOr<T> --> Future<T>, for all T

The first three may seem slightly accidental, but they also seem "natural" (and, of course, as a run-time type they would all be Future<Object> except for printing).

[eernstg]

I've created a CL updating dartLangSpec.tex to say this (including, of course, similar rules for sync* and async*).

The specification doesn't actually prevent an implementation from returning an object whose clausal supertype at Future/Stream/Iterable has an actual type argument which is a proper subtype of the specified return type (that is "the returned instance can be too special"). For instance, with

Future<String> returnsString() async {
  return null;
}

it would be acceptable for an invocation of returnsString to return a Future<Null>. I expect that to be a relatively harmless kind of imprecision, considering it to be a matter of "quality of service" that the implementation won't needlessly set up the future completion action for failure, and when it works it won't hurt, as far as I can see.

[eernstg]

Closing: Said CL has now been landed as commit 8dca855.