awaitNotRequired top-level constant

_AwaitNotRequired const awaitNotRequired

Used to annotate a Future-returning function (including constructors, getters, methods, and operators), or a Future-typed field (including top-level, instance, and static) f. Indicates that the Future value that f returns does not need to be awaited. Any methods that override f in class inheritance, are also expected to conform to this contract.

Tools, such as the analyzer, can use this to understand whether to report that a Future-typed value does not need to be awaited:

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

void fn() {
  log('Message'); // Not important 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, field, or top-level 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 _AwaitNotRequired awaitNotRequired = _AwaitNotRequired();