Notes about asynchronous programing in Dart. In this article I test and learn about two variants of writing asynchronous code in Dart: async/await and Future-based.

Goal

As I learn Dart, I want to reinforce - or rather feel - how asynchronous programming look like. I already have some basic experience with JavaScript and I think Dart Futures are similar.

My goal in this article is to go through a very simple Dart code examples and learn about Futures, making the code a bit more complex bit by bit. I thought it would be funny to try and compare two ways (or flavours) of writing asynchronous code.

Create a future

Let’s create a simple compute function that mimics heavy calculation. After two secons returned future would be completed with value 1.

Future<int> compute({bool throwing: false}) async {
  if (throwing) {
    throw MyError(message: 'calculation exception');
  } else {
    return Future.delayed(Duration(seconds: 2), () => 1);
  }
}

Single optional parameter (false by default) allows to force the function into throwing an exception MyError. Here is the definition of MyError:

class MyError implements Exception {
  final String message;
  final Exception? cause;
  MyError({this.message = "Default error", this.cause = null});
  String toString() => "MyError: ${message}";
}

The throwing parameter would let me test the behavior of the returned future later. I can call compute(..) in two ways: forcing it to throw or not to force:

Complete future with value

Letthe future complete with value. main would call compute() and print the result:

void main(List<String> args) {
  compute().then((v) {
    print(v);
  });
}

or

void main(List<String> args) async {
  print(await compute());
}

Both variants do the same (print “1” after 2 seconds).

I present here both code styles which can be used to express asynchrony in Dart code. Both exist e.g. in JavaScript. If you were ever writing asynchronous code in JS then Dart will feel like home.

• first style is “callback” style in which resulting Future allows to call its method like: then, onError, timeout or catchError. Those methods take other functions that can handle different scenarios of possible future completion (by error or by value).
• second style is called “async/await”; function that is using await must be declared as being async in method signature.

Complete future with exception

main would call compute({throwing: true}) and print result like this:

void main(List<String> args) {
  compute(throwing: true).then((v){
    print(v);
  });
}

or like this:

void main(List<String> args) async {
  print(await compute(throwing: true));
}

Both variants produce:

Unhandled exception:
My error: calculation exception
#0      compute (file:///home/karma/dev/dart/asyncerr/main.dart:3:5)
#1      main (file:///home/karma/dev/dart/asyncerr/main.dart:36:15)
#2      _delayEntrypointInvocation.<anonymous closure> (dart:isolate-patch/isolate_patch.dart:295:32)
#3      _RawReceivePortImpl._handleMessage (dart:isolate-patch/isolate_patch.dart:192:12)

Now, based on the two ways of calling asynchronous code, let’s see what we can do with exceptional situations.

Exceptions

Let’s assume our computation throws exception. What can we do about it? Let’s handle it by printing the exception to stdout. This behavior of handling an error would be implemented in a separate function and would simply print the exception:

void _handleError(Exception e) {
  print("_handleError: $e");
}

I can use it in try-on-catch block in async main:

void main(List<String> args) async {
  try {
    int a = await compute(throwing: true);
    print(a);
  } on Exception catch (e) {
    _handleError(e);
  };
}

which will result in:

_handleError: My error: calculation exception

Note: this code will only catch subclasses of Exception. To handle other types, you need to catch other possible things that are thrown (everything can be thrown: integers, arbitrary objects….) (credits: SO):

try {
  ...
} on Exception catch (exception) {
  ... // only executed if error is of type Exception
} catch (error) {
  ... // executed for errors of all types other than Exception
}

Other variant of the code, using Future’s onError, requires some special attention, because this code simply does not compile:

void main(List<String> args) {
  compute(throwing: true).onError(_handleError)
}

The argument type ‘void Function(Exception)’ can’t be assigned to the parameter type ‘FutureOr Function(Object, StackTrace)’.dartargument_type_not_assignable

so I need to:

1. write a test that would filter out thrown values and only trigger handler if the test passes (here I test that thrown value is of type MyError) and
2. write the handler; however, the handler is expected to actually return a FutureOr (which is a special type denoting that I can return int and Future<int> as well).

In the handler I’m returning 213, and I’m not sure how I could use this value…

Here is what I came to:

void main(List<String> args) {
  compute(throwing: true).onError(
    (error, stackTrace){_handleError(error as MyError) ; return 213; },
    test: (e)=>e is MyError);
}

Oh. I forgot about the code in .then(....) block! Let’s add it:

void main(List<String> args) {
  compute(throwing: true)
  .then((v) {
    print(v);
  }).onError((error, stackTrace) {
    _handleError(error as MyError);
    return 213;
  }, test: (e) => e is MyError);
}

Now Dart recognized that a future in then does not return a Future with int value; it just returns void. Providing an int value in onError is compilation error. Is this really what happens? What if I’m wrong?

Let’s pretend out business case is to take computed value and then classify the value as being small or big. We have a classification function Future<Size> classify(int):

enum Size {small, big, unspecified}

Future<Size> classify(int number) async {
  return number > 100 ?  Size.big : Size.small;
}

Using this function on then(...):

void mainf(List<String> args) {
  compute(throwing: true)
  .then(classify)
  .onError((error, stackTrace) {
    _handleError(error as MyError);
  }, test: (e) => e is MyError);
}

raises compilation error. From vscode:

The body might complete normally, causing 'null' to be returned, but the return type, 'FutureOr<Size>', is a potentially non-nullable type.
 Try adding either a return or a throw statement at the end.

Or from dart:

Error: A non-null value must be returned since the return type 'FutureOr<Size>' doesn't allow null.
 - 'Size' is from 'main.dart'.
  .onError((error, stackTrace) {
           ^

Fix it: provide correct the completion value

Aha! Let’s fix that by providing Size.unspecified:

void main(List<String> args) {
  compute(throwing: true)
  .then(classify)
  .onError((error, stackTrace) {
    _handleError(error as MyError);
    return Size.unspecified;
  }, test: (e) => e is MyError);
}

What is going on here?

Futures can be executed in succession. We are building a “pipeline” of execution. Each level of execution returns other future (possibly with other type). onError’s type of handler function depends on what future we’re handling. Although we’re handling errors thrown anywhere up the stream, we only need to provide completion value for last future in the chain, i.e. result of classify.

Observe the output of the above execution:

_handleError: My error: calculation exception

Handling exception trown in classify

If classify threw an exception, what would be the output? I’d expect that nothing would change - actually, classify is never called, because exception is thrown higher in the pipe, in compute. What if compute() provides int value, and classify fails? Let’s see:

Firs, make classify throw on negative numbers and make compute() use provided result:

Future<Size> classify(int number) async {
  if (number < 0) {
    throw MyError(message: "classify error: negative");
  }
  return number > 100 ? Size.big : Size.small;
}

Future<int> compute({bool throwing: false, int result: 1}) async {
  if (throwing) {
    throw MyError(message: 'calculation exception');
  } else {
    return Future.delayed(Duration(seconds: 2), () => result);
  }
}

Now, let’s run the example:

• with negative compute value
• throwing: false What would happen?
• compute would return normally after 2 seconds
• classify would throw exception

So, would onError correctly report classify exception? Let’s find out:

void main(List<String> args) {
  compute(throwing: false, result: -10)
  .then(classify)
  .onError((error, stackTrace) {
    _handleError(error as MyError);
    return Size.unspecified;
  }, test: (e) => e is MyError);
}

_handleError: My error: classify error: negative

😄 That was easy! onError handles exception thrown somewhere up the chain. Would the same be true for async variant?

void main(List<String> args) async {
  try {
    int a = await compute(throwing: false, result: -120);
    Size size = await classify(a);
    print(size);
  } on Exception catch (e) {
    _handleError(e);
  }
  ;
}

The same output! Great!

Using a value in case of exception

I’m wondering: how can I use the value that onError returned to complete classify returned future? In Future-base variant I can further chain another then(_) call and use the value with which previous Futire was completed with (i.e.Size.unspecified):

void main(List<String> args) {
  compute(throwing: false, result: -1).then(classify).onError(
      (error, stackTrace) {
    _handleError(error as MyError);
    return Size.unspecified;
  }, test: (e) => e is MyError)
  .then((value) {
    print("Size is $value");
  });
}

results in

_handleError: My error: classify error: negative
Size is Size.unspecified

and async variant requires explicit asignment in on-catch block:

void main(List<String> args) async {
  Size? size = null;
  try {
    int a = await compute(throwing: false, result: -1);
    size = await classify(a);
    print(size);
  } on Exception catch (e) {
    _handleError(e);
    size = Size.unspecified;
  } finally {
    print("Size is $size");
  }
  ;
}

So, it seems everything can be done in both variants.

How about timout?

Timeout

Let’s say that we are presented with a business requirement to return Size.unspecified every time the computation takes longer than 500 ms. In order to test that, let’s prepare compute() so that it would take duration (of type Duration):

Future<int> compute(
    {bool throwing: false,
    int result: 1,
    Duration dur: const Duration(seconds: 2)
    }) async {
  if (throwing) {
    throw MyError(message: 'calculation exception');
  } else {
    return Future.delayed(dur, () => result);
  }
}

So, if we change the compute future to timeout after requestedTimeout, that’s all: our on Exception catch (e) block would catch TimeoutException and correctly assign size:

void maina(List<String> args) async {
  Size? size = null;
  Duration requestedTimeout = Duration(milliseconds: 500);
  try {
    int a = await compute(
            throwing: false, result: 200, dur: Duration(seconds: 2))
        .timeout(requestedTimeout);
    size = await classify(a);
    print(size);
  } on Exception catch (e) {
    _handleError(e);
    size = Size.unspecified;
  } finally {
    print("Size is $size");
  }
  ;
}

Output:

_handleError: TimeoutException after 0:00:00.500000: Future not completed
Size is Size.unspecified

With Future variant some more work is needed. Not only should we set timeout on the future, byt also note that our test function in onError would effectively prevent handlng TimeoutException (it won’t allow _handleError to fire as well as won’t complete the Future with Size.unspecified).

Setting only timeout in Future variant gives this output:

Unhandled exception:
TimeoutException after 0:00:00.500000: Future not completed

Let’s relax the test, or actually, let’s remove it altogether; we could call _handleError conditionally, but return (i.e. complete) proper Size unconditionally:

void mainf(List<String> args) {
  Duration requestedTimeout = Duration(milliseconds: 500);
  compute(throwing: false, result: -1)
  .timeout(requestedTimeout)
  .then(classify)
  .onError(
      (error, stackTrace) {
    if (error is MyError) {
      _handleError(error);
    }
    return Size.unspecified;
  }).then((value) {
    print("Size is $value");
  });
}

Now the above code results in proper handling of required value:

Size is Size.unspecified

Summary

Asynchronous execution syntax, language support or at least a library support is present in almost all major languages:

• Scala
• Rust
• Python
• JavaScript
• Dart

Sometimes the asynchrony is single-threaded (JS) and sometimes the tasks are scheduled on a number of OS threads (go).

Different approach exist in

• Go: channels where goroutines are handled by the runtime (i.e. schedued automatically - by language runtime - for execution on syste threads)
• Java with completable futures where currently using Furure-based approach requires thinking about actual executors (and underlying thread pools). Projec Loom and the arrival of JEPP 428 would introcude structured concurrency which furter complicates/simplifies the development of concurrent/asynchronous code.

No matter what language you choose, you need to learn the API, write small programs to get used to the API and have a grasp of how to deal with exceptional situations, read, experiment and be ready for all the troubles the async execution environment brings (with non-deterministic behavior, debugging, reasoning about code flow - to name a few).

And don’t ever think you know concurrent programming. It is hard (tm) and our carbon-based hardware would always have problems in processing concurrency (both as a concept and as a code).

Welcome in a new series of articles about Dart programming language.

It is not a beginner tutorial. I focus mainly on features that may be surprising and/or interesting for a Java(Script) developer.

Slides

Slide notes are available here.

The resources:

Start with these:…

1. https://dart.dev/guides/language/language-tour (language overview)
2. https://dartpad.dev/ (write & run in online editor)
3. https://dart.dev/guides/language/spec (language specification page, current spec pdf: 2.10)
4. https://dart.dev/guides/language/effective-dart (good practices)

Basics

… or look below:

1. .dart file is a “module”.
2. top-level functions, variables, constants and classes
3. names starting with “_” (underscore) are private to the module
4. everything is an object
5. null-safety (nullable type by appending ? to type name, like in Kotlin)
6. generics are are reified (accessible at runtime), contrary to Java, where types are erased.
7. type inference; you can declare variables with var.
8. final modifier makes variable assign-once; const modifier makes variable a compile-time constant.
9. import from built-in libraries (import 'dart:html';), local filesystem (import './foo.dart) or external package managed by build tool, like pub (import 'package:test/test.dart';)
10. you can alias a lib, import only one symbol or exclude symbol from import (as, show, hide)
11. asynchrony support with async and await, Future and Stream classes, which are run in same Isolate - see [Concurrency in Dart)[https://api.dart.dev/stable/dart-isolate)
12. sync and async generator functions
13. callable classes: instances can be called with params; implement call method in the class
14. isolates as “threads” without race conditions, see concurrency
15. typedefs (typedef IntList = List<int>;_), also generic, and (recommended) function types, eg: final bool Function(Event) _predicate or final List<void Function(Event)> _observers;
16. Control structures: for (with iterator in form for elem of iter), while(){}, do{} while(), switch (without pattern matching)
17. Extension methods add functionality to existing classes. Resolve to a static type of the receiver (like in Kotlin).

Classes

As Java developers we usually think in terms of classes. Dart supports classs, allows to define abstract classes and offers mixins (that define behaviors and don’t have constructors) with which a class can be extended.

See classes section in lnguage tour.

If, by any chance, you are a JavaScript developer, you might want to read a decicated guide for JavaScript prorgammers with examples.

Libraries

If you want to dive deep into libraries, start with standard library. Then, depending on the target platform, look at native or javacript secions below.

Standard library

These libraries workk on all platforms:

• dart:core
• dart:async and package:async
• dart:collection and package:collection
• dart:convert and package:convert
• dart:developer (only in Native JIT and dartdevc)
• dart:math
• dart:typed_data (and also package:typed_data)

Dart native

Dart native platform allows to create AOT- and JIT-compiled code and provides a few special libraries:

• dart:ffi and package:ffi
• dart:io and package:io
• dart:isolate
• dart:mirrors

Javascript

Dart Web platform allows developing for web.

• dart:html
• dart:indexed_db
• dart:js
• dart:js_util
• package:js - also JavaScript interoperability
• dart:svg
• dart:web_audio
• dart:web_gl

Nice cookbook articles:

The cookbook is a nice collection of hints on how to implement specific Dart/Flutter usecases, for example: parsing json in backgroud, return data from screen, make authenticated requests or persist data with sqlite, how to write integration tests…

Next steps

As a next step, we may want to write some short prorgams just to check out some ideas and get used to the language itself. Stay tuned!

Happy coding!