The following example is somewhat contrived but I'm trying understand the relationship between a Completer and the future generated by an await.
In the example below the 'doCalc' method contains an 'await' call and a Completer.
Its my understanding that when dart hits the 'await' statement that it immediately stops executing the method and returns a future.
If you run the code in dartpad you can see this in the output. The value = Instance of '_Future<int>' line is printed immediately.
This matches my expectation (i.e. await cause the method to return immediately).
You can see from the 'value=' line that doCalc has returned a Future<int>.
This is also as expected.
The problem I'm having is that the last line of doCalc also returns a future. In this case the future generated by the completer.
As such it appears that doCalc returns TWO different futures.
1) The first one dart implicitly returns when await is called.
2) The second one I explicitly return via the return statement.
Given that the value of 'res' must contain the first future (as we print its value before the completer's future is returned) how is it that the line res.then waits until the second future completes.
There appears to be some magic here but I can't find any documentation on it.
Dart pad link:
https://dartpad.dev/a42cce3edf01b222206a627e8c8106af
import 'dart:async';
void main() {
print('hi');
var res = doCalc();
print('value = ${res}');
res.then((result) => print('result = $result'));
}
Future<int> doCalc() async
{
var done = Completer<int>();
await Future.delayed(Duration(seconds: 4),
() {
done.complete(10);
});
return done.future;
}
An async function returns a future that it creates itself. It does so "immediately", which means that it executes the body until the first asynchronous delay (await or await for) before the future is returned.
Any return statement inside an async function is used to complete the returned future.
If your async function returns a Future<int>, then your return statements must return either an int or a Future<int>.
In the former case, the returned future is completed with that integer.
In the latter case, the returned future will complete with the same result as the return-future (let's name it that) when the return-future completes.
It is as if a return expression; in an async function is effectively a return await expression;.
In this example, the line:
return done.future;
can be read as
return await done.future;
and that should explain the behavior you see.
Related
I wrote a very small package for myself in order to execute futures sequentially, it does the following:
Ensures that futures are executed in the order they are "appended", each waiting for the previous future to finish.
Passes the last returned result to the next future being executed.
Returns the value of the appended future.
Here is the complete code of the package:
import 'dart:async';
class FutureQueue<T> {
final Duration? _timeLimit;
Future<T?> _future;
FutureQueue({Duration? timeLimit})
: _timeLimit = timeLimit,
_future = Future.value();
FutureQueue.seeded(
FutureOr<T> seed, {
Duration? timeLimit,
}) : _timeLimit = timeLimit,
_future = Future.value(seed);
Future<T?> get future => _future;
/// Adds the given [future] to queue. Note that the [previous] value will be
/// null if the last operation caused an exception.
Future<T?> append(FutureOr<T> Function(T? previous) future,
{Duration? timeLimit}) {
return _future = _future.catchError((_) {}).then((previous) {
if (timeLimit != null || _timeLimit != null) {
return _withTimeout(future(previous), timeLimit ?? _timeLimit!);
}
return future(previous);
});
}
Future<T> _withTimeout(FutureOr<T> future, Duration timeLimit) {
return Future.value(future).timeout(timeLimit);
}
/// Waits for queued events to finish.
Future<void> close() async {
await _future;
}
}
I've seen this error reported in production when calling append with a Future that returns a non-nullable value and then using the null-check operator to assert that it is not null:
_CastError: Null check operator used on a null value
File "api_token_repo.dart", line 37, in ApiTokenRepo.fetch.<fn>
File "zone.dart", line 1434, in _rootRunUnary
File "<asynchronous suspension>"
File "user_bloc.dart", line 169, in UserBloc._mapUserProfileReloadStarted
File "<asynchronous suspension>"
File "user_bloc.dart", line 71, in UserBloc._configureEventHandling.<fn>
File "<asynchronous suspension>"
File "bloc.dart", line 211, in Bloc.on.<fn>.handleEvent
The code where the exception is thrown is as follows:
Future<ApiToken> fetch() {
return _futureQueue
.append((_) => _fetchAndSave())
.then((apiToken) => apiToken!); // <- Exception thrown here
}
Future<ApiToken> _fetchAndSave() async {
final apiToken = await _fetcher();
_saver(apiToken);
return apiToken;
}
The exception is thrown when calling apiToken! and I can't understand how this is possible. My understanding is that if an exception was thrown when calling _fetchAndSave then the then call would be bypassed since an error occurred. If an error didn't occur then _fetchAndSave doesn't allow a non-null value to be returned.
My first impression was that perhaps it is a race condition where append is called twice and the second call is made before the first finishes and the result of the second is being returned to the first call of append but my (admittedly not great) understanding of how dart code is executed led me to believe that this is not possible. I've tried to simulate such circumstances with tests making hundreds of calls to append with different delays but I've been unable to reproduce such a result.
Note that I am using the timeout functionality of my FutureQueue class if that is helpful.
I am aware of alternative packages for making Futures run in a sequence (I'm not sure if any exist with exactly the same functionality) but I would like to fully understand the issue as it makes be doubt my understanding of how Dart is executed.
As far as I can tell, you must be running in unsound mode (sound null safety is not enabled), and you are having a null leak in through some non-null-safe library.
For instance, where does _fetcher come from? Is it delegating to an implementation provided by another library? Possibly that library is giving you a function which returns null in some scenario?
Here is a gist illustrating the situation https://gist.github.com/jakemac53/d95b9fd8aa55d03cf306b6c7b897132d.
I have a confusion in understanding Dart's async/await functionality. Most tutorials use the following example:
Future<String> createOrderMessage() async {
var order = await fetchUserOrder();
return 'Your order is: $order';
}
Future<String> fetchUserOrder() =>
// Imagine that this function is
// more complex and slow.
Future.delayed(
const Duration(seconds: 2),
() => 'Large Latte',
);
Future<void> main() async {
print('Fetching user order...');
print(await createOrderMessage());
}
I understand that the fetchUserOrder function returns a Future. Anyone who calls this function will immediately get a Future object as a result but this Future object may not have the real result value at that time. It will be filled up in "future".
Now, the createOrderMessage function calls: await fetchUserOrder(); This means, the control will wait till fetchUserOrder() returns a completed/non-empty Future. Am I right here? Is this what await does?
If that is correct, it means, the createOrderMessage function is essentially synchronous now because it won't return until the Future returned by fetchUserOrder is filled. Thus, the order variable in this function is initialized with a completed Future. Then why does this function need the "async" keyword in its function declaration? What does it signify?
Second confusion is if Dart is single threaded, when and how exactly is an async function executed? If I invoke multiple method calls that return Futures like this without await:
...
Future<A> fa = getA();
Future<B> fb = getB();
Future<C> fa = getC();
...
Will the functions getA, getB, and getC be executed sequentially in the background or they will be executed "in parallel" somehow?
Now, the createOrderMessage function calls: await fetchUserOrder(); This means, the control will wait till fetchUserOrder() returns a completed/non-empty Future. Am I right here? Is this what await does?
Yes. the await keyword means you get the completed T instead of Future<T> in return. So:
var a = fetchUserOrder(); // Type of a: Future<String>
var b = await fetchUserOrder(); // Type of b: String
When you use await, you tell the code to await the completion of the process and get the actual result. But without await, the stream is in the future and is in process until you await it somewhere else.
why does this function need the "async" keyword in its function declaration?
It's a rule to specify long-running functions. So when a function awaits for a long running process to complete, the function itself is also a long-running process. Why? Because it's waiting for another one to complete.
Therefore, you need to specify async for that as well. When another function is calling this one, it also knows this one might be long-running.
In short, every awaitable function needs to be in an async function.
Second confusion is if Dart is single threaded, when and how exactly is an async function executed?
You're mixing the concept of parallelism with asynchronous. An async process does not have to be done in multi thread.
Async processes can be one one at time, but in a different order in compare to synchronous code.
Take a look at this article which explains asynchronous in a single thread.
Now, the createOrderMessage function calls: await fetchUserOrder(); This means, the control will wait till fetchUserOrder() returns a completed/non-empty Future. Am I right here? Is this what await does?
If that is correct, it means, the createOrderMessage function is essentially synchronous now because it won't return until the Future returned by fetchUserOrder is filled. Thus, the order variable in this function is initialized with a completed Future.
await allows asynchronous functions to have the appearance of synchronous functions by allowing asynchronous code to be structured very similarly to synchronous code. In your example, it's syntactic sugar for registering a Future.then() callback and immediately returning:
Future<String> createOrderMessage() {
var future = fetchUserOrder().then((order) {
return 'Your order is: $order';
});
return future;
}
await defers execution of the rest of that function; it does not wait and block execution of your entire thread. Your program will continue running its event loop, possibly allowing other asynchronous operations to make progress.
Will the functions getA, getB, and getC be executed sequentially in the background or they will be executed "in parallel" somehow?
As I mentioned in comments, it depends on how getA, getB, and getC are implemented. They could run in parallel, such as if they run in separate Dart isolates or in separate threads in the Dart VM/runtime.
How does Dart run asynchronous code without blocking?
For example:
void test(User user) async {
print('test');
String fullName = user.firstName + ' ' + user.lastName;
final result = await sendRequest(fullName);
print('${result}');
}
I understand that when Dart runs async function, it executes code before await and then wraps the remaining code into Future and puts it into Event Loop. But, how does that Future what we're awaiting for (await sendRequest(fullName)) not blocking running the other, synchronous code? We should wait for request for complete but it also requires some code to check that we've received or not received response. How does it not block other operations, like button clicks?
The function returns at the first await. It returns a future which will later be completed (which is then ignored because of the void return type). Everything else in the function happens in reaction to callbacks from other futures (or streams, if you use await for).
The async function here is basically rewritten into something like:
void test(User user) {
print('test');
String fullName = user.firstName + ' ' + user.lastName;
return sendRequest(fullName).then((final result) { // <-- Returns here, synchronously.
print('${result}'); // <-- Gets called by the future of `sendRequst(fullName)`.
});
}
This transformation is similar to a continuation-passing style transformation in the it takes the continuation (the control flow in the body of the function after the await) and makes it into a function.
(In reality, the transformation is more complicated because it needs to account for loops, try/catch/finally, and even break statements. Because of that, even a simple example like this one will likely be converted into something more complicated than absolutely necessary).
Dart offers a FutureOr class, that allows writing:
FutureOr<int> future;
future = 42; // valid
future = Future.value(42); // also valid
I would assume that FutureOr would be useful to remove the unnecessary delay caused by the event loop if the value can be read synchronously.
But that doesn't seem to be the case, as showcased by:
import 'dart:async';
void main() async {
print('START');
futureOrExample();
print('END');
}
void futureOrExample() async {
FutureOr<int> futureOr = 42;
print('before await');
await futureOr;
print('end await');
}
which prints:
START
before await
END
end await
when I would expect:
START
before await
end await
END
In that case, why does FutureOr (or more generally await 42) work this way?
Similarly, what's the purpose of FutureOr in that situation since it produces the same result as Future?
I know that I could use SynchronousFuture to achieve the desired result, but I'm just trying to understand what's the use of FutureOr.
The use of FutureOr, as introduced with Dart 2, is to allow you to provide either a value or a future at a point where the existing Dart 1 API allowed the same thing for convenience, only in a way that can be statically typed.
The canonical example is Future.then. The signature on Future<T> is Future<R> then<R>(FutureOr<R> action(T value), {Function onError}).
The idea is that you can have an action on the future's value which is either synchronous or asynchronous. Originally there was a then function which took a synchronous callback and a chain function which took an asynchronous callback, but that was highly annoying to work with, and in good Dart 1 style, the API was reduced to one then method which took a function returning dynamic, and then it checked whether it was a future or not.
In Dart 1 it was easy to allow you to return either a value or a future. Dart 2 was not as lenient, so the FutureOr type was introduced to allow the existing API to keep working. If we had written the API from scratch, we'd probably have done something else, but migrating the existing asynchronous code base to something completely different was not an option, so the FutureOr type was introduced as a type-level hack.
The await operation was also originally defined to work on any object, long before FutureOr existed. For consistency and smaller code, an await e where e evaluated to a non-future would wrap that value in a future and await that. It means that there is only one quick and reusable check on a value (is it a future, if not wrap it), and then the remaining code is the same. There is only one code-path.
If the await worked synchronously on non-Future values, there would have to be a synchronous code path running through the await, as well as an asynchronous path waiting for a future. That would potentially double the code size, for example when compiling to JavaScript (or worse, if there were more awaits in the same control flow, you could get exponential blow-up for a naive implementation). Even if you avoided that by just calling the continuation function synchronously, it would likely be confusing to some readers that an await would not introduce an asynchronous gap. A mistake around that can cause race conditions or things happening in the wrong order.
So, the original design, predating FutureOr, was to make all await operations actually wait.
The introduction of FutureOr did not change this reasoning, and even if it did, it would now be a breaking change to not wait in places where people expect their code to actually give time for other microtasks to run.
The await keyword always lock the function execution.
Writing:
await 42
Is equivalent to:
await Future.value(42)
The reason being:
This is how await works in Javascript
it makes the behavior of await consistent.
Now, what's the purpose of FutureOr then?
FutureOr was never intended as a way to potentially make await synchronous.
Instead, it is an implementation detail of Future.
Without FutureOr, writing the following would not compile:
Future(() {
return 42; // compile error, not a Future
});
Future<int> future;
future.then((value) {
return value * 2; // compile error, not a Future
});
Instead, we would have to wrap all values in a Future.value like so:
Future<int> future;
future.then((value) {
return Future.value(value * 2);
});
for those who are still confused
I found good explanation https://itnext.io/what-is-futureor-in-dart-flutter-681091162c57 without diving into details
This piece of code could explain the target and real use cases of FutureOr
abstract class IDBService {
FutureOr<String> fetch();
}
class FirebaseRemoteService extends IDBService {
#override
Future<String> fetch() async => await 'data';
}
class LocalHiveDbService extends IDBService {
#override
String fetch() => 'data';
}
so in implementations of IDBService
the return type can be Future or String at the same time now!
Coming late to the discussion.
Updating my Dart comprehension - pardon my C++/JS -ish approach.
Seems like this would be useful for singleton initiation. Consider following:
import 'dart:async';
class AClass {
static String _info = '';
static FutureOr<String> get info async {
if (_info.isEmpty) {
print('--> is empty...');
_info = await Future.delayed(Duration(seconds:2),
() => "I'm alive!!");
}
else {
print('--> not empty');
}
return _info;
}
}
Future<void> main() async {
String info = await AClass.info;
print('Fist call: ' + info);
info = await AClass.info;
print('Second call: ' + info);
}
It works as expected - in either case, whether the _info member has been instantiated or not, the getter returns a valid string.
It works fine if I just use a Future<String> specifier in the getter, too. The current implementation makes FutureOr seem mostly like a self-documentation exercise (can return a Future<String> or a String...)
But, even if await currently always locks the execution, a future update may allow it to work as expected, in which case using the FutureOr construct would anticipate updates.
(Aside: I imagine this example could be condensed using an Optional wrapping the _info member, but that's a different exercise...)
I needed to use FutureOr today. I wanted to call a function that might be asynchronously (not always).
String callbackOne() => "hello";
Future<String> callbackTwo() async => (await Future.delayed(Duration(seconds: 1),() => "This is a sentence"));
Problem
I can do getLengthOfResult(callbackOne), but not getLengthOfResult(callbackTwo). Conversely, if accept an async callback, I can't use the sync callback.
DartPad
Future<int> getLengthOfResult(String Function() callback) async {
return callback().length;
}
Solution
DartPad
Future<int> getLengthOfResult(FutureOr<String> Function() callback) async {
// I can await on callbackOne, even though it returns a String.
final result = await callback();
return result.length;
}
main() {
getLengthOfResult(callbackOne);
getLengthOfResult(callbackTwo);
}
I have a setMethodCallHandler which runs a callback from my Java code, and I want it to set a Future containing the result. Something like
Future<String> fun() async {
return setMethodCallHandler((MethodCall call) {
return () async {return call.arguments["arg"];}();
});
}
What I want to be able to do is if call.argument will return "abc",
var a = await fun();
a will be equal to "abc"
The only information I found was the documentation on setMethodCallHandler:
If the future returned by the handler completes with a result, that value is sent back to the platform plugin caller wrapped in a success envelope as defined by the codec of this channel. If the future completes with a PlatformException, the fields of that exception will be used to populate an error envelope which is sent back instead.
But I don't understand how can I get the "platform plugin caller wrapped in a success envelope as defined by the codec of this channel"?
I'm guessing, but correct me if I'm wrong, that setMethodCallHandler does not return a value, it only sets up a function to be called later.
So, you can't use the return value of the setMethodCallHandler for anything.
That effectively means that you have an "event" of a kind, one that you want to "convert" into a future completion. To do that, you use a Completer to create and later complete a Future.
Future<String> fun() {
var completer = new Completer<String>();
setMethodCallHandler((MethodCall call) {
completer.complete(call.arguments["arg"]);
}
return completer.future;
}
Using async functions works when your events all come from futures or streams, but when you get other kinds of events (like port events, I/O callbacks or timers) and you want to map that back to future/stream events, you use either a Completer to complete a future or a StreamController to add events to a stream.