Add unawaited to package:meta.

pkg/meta/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.1.7
+
+* Add `unawaited` to mark that a `Future` result is intentionally ignored,
+  silencing the `unawaited_futures` lint.
+
 ## 1.1.6
 
 * Set max SDK version to <3.0.0.

pkg/meta/README.md

@@ -1,17 +1,17 @@
 # Annotations for Static Analysis
 
-This package defines annotations that can be used by the tools that are shipped
-with the Dart SDK.
+This package defines annotations, and functions that act like annotations for
+expressions, that can be used by the tools that are shipped with the Dart SDK.
 
 ## Library Structure
 
 The annotations in this package are defined in two libraries.
 
-The library in `meta.dart` defines annotations that can be used by static
-analysis tools to provide a more complete analysis of the code that uses them.
-Within the SDK, these tools include the command-line analyzer (`dartanalyzer`)
-and the analysis server that is used to power many of the Dart-enabled
-development tools.
+The library in `meta.dart` defines annotations and functions that can be used
+by static analysis tools to provide a more complete analysis of the code that
+uses them. Within the SDK, these tools include the command-line analyzer
+(`dartanalyzer`) and the analysis server that is used to power many of the
+Dart-enabled development tools.
 
 The library in `dart2js.dart` defines annotations that provide hints to dart2js
 to improve the quality of the JavaScript code that it produces. These

pkg/meta/lib/meta.dart

@@ -18,6 +18,8 @@
 /// in the language tour.
 library meta;
 
+import 'dart:async' show Future;
+
 /// Used to annotate a function `f`. Indicates that `f` always throws an
 /// exception. Any functions that override `f`, in class inheritence, are also
 /// expected to conform to this contract.
@@ -244,6 +246,26 @@ class Required {
   const Required([this.reason]);
 }
 
+/// Used to indicate to tools that [future] is intentionally not `await`-ed.
+///
+/// In an `async` context, it is normally expected than all [Future]s are
+/// awaited, and that is the basis of the lint `unawaited_futures`. However,
+/// there are times where one or more futures are intentionally not awaited.
+/// This function may be used to ignore a particular future. It silences the
+/// `unawaited_futures` lint.
+///
+/// ```
+/// Future<void> saveUserPreferences() async {
+///   await _writePreferences();
+///
+///   // While 'log' returns a Future, the consumer of 'saveUserPreferences'
+///   // is unlikely to want to wait for that future to complete; they only
+///   // care about the preferences being written).
+///   unawaited(log('Preferences saved!'));
+/// }
+/// ```
+void unawaited(Future<void> future) {}
+
 class _AlwaysThrows {
   const _AlwaysThrows();
 }

pkg/meta/pubspec.yaml

@@ -1,5 +1,5 @@
 name: meta
-version: 1.1.6
+version: 1.1.7
 author: Dart Team <[email protected]>
 homepage: https://github.com/dart-lang/sdk/tree/master/pkg/meta
 description: >