awaitNotRequired top-level constant

Object const awaitNotRequired

Annotation on asynchronous function whose Future can be ignored.

Used to annotate a Future-returning function (including constructors, getters, methods, and operators), or a Future-typed variable declaration (including top-level, instance, and static variables). Indicates that the Future value does not need to be awaited. This means both that the future will not complete with an error, and that any value it completes with does not need to be disposed or handled in any way.

Any instance member that override an annotated member, are also expected to conform to this contract.

Tools, such as the analyzer, can use this to decide whether to report that a Future-typed value needs to be awaited:

@awaitNotRequired
Future<LogMessage> log(String message) { ... }

void fn() {
  log('Message'); // Not necessary to wait for logging to complete.
}

Without the annotation on log, the analyzer may report a lint diagnostic at the call to log, such as discarded_futures or unawaited_futures, regarding the danger of not awaiting the function call, depending on what lint rules are enabled.

Tools, such as the analyzer, can also provide feedback if

  • the annotation is associated with anything other than a constructor, function, method, operator or variable, or
  • the annotation is associated with a constructor, function, method, or operator that does not return a Future, or
  • the annotation is associated with a field or top-level variable that is not typed as a Future.

Implementation

const Object awaitNotRequired = _AwaitNotRequired();