Let's change the code from the previous section into async, as follows:

import 'dart:io';

main() {
  File file = new File("data.txt");
  file.open().then(processFile);
}

processFile(RandomAccessFile file) {
  file.length().then((int length) {
    file.read(length).then(readFile).whenComplete(() {
      file.close();
    });
  });
  }

readFile(List<int> content) {
  String contentAsString = new String.fromCharCodes(content);
  print("Content:  $contentAsString");
}

As you can see, the Future class is a proxy for an initially unknown result and returns a value instead of calling a callback function. Future can be created by itself or with Completer. Different ways of creating Future must be used in different cases. The separation of concerns between Future and Completer can be very useful. On one hand, we can give Future to any number of consumers to observe the resolution independently; on the other hand, Completer can be given to any number of producers and Future will be resolved by the one that resolves it first. Future represents the eventual value that is returned from the callback handler, and it can be in one of the following states:

A consumer can register callbacks to handle the value or error of the Future class. I slightly changed our example to manage exceptions and deliberately used the wrong filename here to throw an exception:

//…
main() {
  File file = new File("data1.txt");
  file.open().then(processFile).catchError((error, stackTrace) {
    print("Catched error is $error
$stackTrace");
  }, test:(error) {
    return error is FileSystemException;
  }).whenComplete((){
    print("File closed");
  });
}
//…

In the preceding code, we added the catchError method to catch errors. Pay attention to the optional test parameter of the catchError method. This parameter is the function that is called first if Future completes with an error, so you have a chance to check if the instance of an error must be handled in the catchError method. If optional test parameter is omitted, it defaults to a function that always returns true. If the optional test parameter returns true, the function, specified as the first parameter of catchError, is called with the error and possibly stack trace, and the returned Future is completed with the result of the call of this function. The resulting exceptions will look like this:

Catched error is FileSystemException: Cannot open file, path = 'data1.txt' (OS Error: The system cannot find the file specified.
, errno = 2)
#0     _File.open.<anonymous closure> (dart:io/file_impl.dart:349)
#1     _RootZone.runUnary (dart:async/zone.dart:1082)
//…
File closed

If the optional test parameter returns false, the exception is not handled by the catchError method and the returned Future class is completed with the same error and stack trace.

Last but not least, the Future class has the whenComplete method. This method has one parameter that is considered a function, which is always called in the end regardless of the future result (refer to the last statement in the preceding code).

Now when we are finished with definitions, let's discuss the different factory constructors of Future.

Future calc = new Future(computation);
calc.then((res) => print(res));

Future calc = new Future.microtask(computation);
calc.then((res) => print(res));

Future calc = new Future.sync(computation);
calc.then((res) => print(res));

Future valueFuture = new Future.value(true);
valueFuture.then((res) => print(res));

try {
  throw new Error();
} on Error catch(ex, stackTrace) {
  Future errorFuture = new Future.error(ex, stackTrace);
  errorFuture.catchError((err, stack) => print(err));
}

Future calc = new Future.delayed(
      new Duration(seconds:1), computation);
calc.then((res) => print(res));