CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, height=device-height, initial-scale=1, user-scalable=no"> <meta name="description" content="API docs for the Future class from the dart:async library, for the Dart programming language."> <title>Future class - dart:async library - Dart API</title> <link rel="canonical" href="https://api.dart.dev/dart-async/Future-class.html"> <link rel="preconnect" href="https://fonts.gstatic.com"> <link href="https://fonts.googleapis.com/css2?family=Roboto+Mono:ital,wght@0,300;0,400;0,500;0,700;1,400&display=swap" rel="stylesheet"> <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0" rel="stylesheet"> <link rel="stylesheet" href="../static-assets/github.css?v1"> <link rel="stylesheet" href="../static-assets/styles.css?v1"> <link rel="icon" href="../static-assets/favicon.png?v1">  <script async src="https://www.googletagmanager.com/gtag/js?id=G-VVQ8908SJ5"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'G-VVQ8908SJ5'); </script> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link rel="preload" href="https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@400&family=Google+Sans:wght@500&display=swap" as="style"> <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@400&family=Google+Sans:wght@500&display=swap"> <link rel="stylesheet" href="https://www.gstatic.com/glue/cookienotificationbar/cookienotificationbar.min.css"> </head> <body data-base-href="../" data-using-base-href="false" class="light-theme"> <div id="overlay-under-drawer"></div> <header id="title"> menu <ol class="breadcrumbs gt-separated dark hidden-xs"> <li><a href="../index.html">Dart</a></li> <li><a href="../dart-async/dart-async-library.html">dart:async</a></li> <li class="self-crumb">Future<T> class</li> </ol> <div class="self-name">Future</div> <form class="search navbar-right" role="search"> <input type="text" id="search-box" autocomplete="off" disabled class="form-control typeahead" placeholder="Loading search..."> </form> <div class="toggle" id="theme-button" title="Toggle brightness"> <label for="theme"> <input type="checkbox" id="theme" value="light-theme"> dark_mode light_mode </label> </div> </header> <main> <div id="dartdoc-main-content" class="main-content" data-above-sidebar="dart-async/dart-async-library-sidebar.html" data-below-sidebar="dart-async/Future-class-sidebar.html"> <div> <div id="external-links" class="btn-group"><a title="View source code" class="source-link" href="https://github.com/dart-lang/sdk/blob/88c9758ef131d430d8ce595c6bfb4c90574d3ddd/sdk/lib/async/future.dart#L229">description</a></div> <h1>Future<T> class <a href="https://dart.dev/language/class-modifiers#abstract" class="feature feature-abstract" title="This type can not be directly constructed.">abstract</a> <a href="https://dart.dev/language/class-modifiers#interface" class="feature feature-interface" title="This class can only be implemented (not extended or mixed in).">interface</a> </h1></div> <section class="desc markdown"> The result of an asynchronous computation. An asynchronous computation cannot provide a result immediately when it is started, unlike a synchronous computation which does compute a result immediately by either returning a value or by throwing. An asynchronous computation may need to wait for something external to the program (reading a file, querying a database, fetching a web page) which takes time. Instead of blocking all computation until the result is available, the asynchronous computation immediately returns a <code>Future</code> which will eventually "complete" with the result. <h3 id="asynchronous-programming">Asynchronous programming</h3> To perform an asynchronous computation, you use an <code>async</code> function which always produces a future. Inside such an asynchronous function, you can use the <code>await</code> operation to delay execution until another asynchronous computation has a result. While execution of the awaiting function is delayed, the program is not blocked, and can continue doing other things. Example: <pre class="language-dart"><code class="language-dart">import "dart:io"; Future<bool> fileContains(String path, String needle) async { var haystack = await File(path).readAsString(); return haystack.contains(needle); } </code></pre> Here the <code>File.readAsString</code> method from <code>dart:io</code> is an asynchronous function returning a <code>Future<String></code>. The <code>fileContains</code> function is marked with <code>async</code> right before its body, which means that you can use <code>await</code> inside it, and that it must return a future. The call to <code>File(path).readAsString()</code> initiates reading the file into a string and produces a <code>Future<String></code> which will eventually contain the result. The <code>await</code> then waits for that future to complete with a string (or an error, if reading the file fails). While waiting, the program can do other things. When the future completes with a string, the <code>fileContains</code> function computes a boolean and returns it, which then completes the original future that it returned when first called. If a future completes with an error, awaiting that future will (re-)throw that error. In the example here, we can add error checking: <pre class="language-dart"><code class="language-dart">import "dart:io"; Future<bool> fileContains(String path, String needle) async { try { var haystack = await File(path).readAsString(); return haystack.contains(needle); } on FileSystemException catch (exception, stack) { _myLog.logError(exception, stack); return false; } } </code></pre> You use a normal <code>try</code>/<code>catch</code> to catch the failures of awaited asynchronous computations. In general, when writing asynchronous code, you should always await a future when it is produced, and not wait until after another asynchronous delay. That ensures that you are ready to receive any error that the future might produce, which is important because an asynchronous error that no-one is awaiting is an uncaught error and may terminate the running program. <h3 id="programming-with-the-future-api">Programming with the <code>Future</code> API.</h3> The <code>Future</code> class also provides a more direct, low-level functionality for accessing the result that it completes with. The <code>async</code> and <code>await</code> language features are built on top of this functionality, and it sometimes makes sense to use it directly. There are things that you cannot do by just <code>await</code>ing one future at a time. With a <a href="../dart-async/Future-class.html">Future</a>, you can manually register callbacks that handle the value, or error, once it is available. For example: <pre class="language-dart"><code class="language-dart">Future<int> future = getFuture(); future.then((value) => handleValue(value)) .catchError((error) => handleError(error)); </code></pre> Since a <a href="../dart-async/Future-class.html">Future</a> can be completed in two ways, either with a value (if the asynchronous computation succeeded) or with an error (if the computation failed), you can install callbacks for either or both cases. In some cases we say that a future is completed with another future. This is a short way of stating that the future is completed in the same way, with the same value or error, as the other future once that other future itself completes. Most functions in the platform libraries that complete a future (for example <a href="../dart-async/Completer/complete.html">Completer.complete</a> or <a href="../dart-async/Future/Future.value.html">Future.value</a>), also accepts another future, and automatically handles forwarding the result to the future being completed. The result of registering callbacks is itself a <code>Future</code>, which in turn is completed with the result of invoking the corresponding callback with the original future's result. The new future is completed with an error if the invoked callback throws. For example: <pre class="language-dart"><code class="language-dart">Future<int> successor = future.then((int value) { // Invoked when the future is completed with a value. return 42; // The successor is completed with the value 42. }, onError: (e) { // Invoked when the future is completed with an error. if (canHandle(e)) { return 499; // The successor is completed with the value 499. } else { throw e; // The successor is completed with the error e. } }); </code></pre> If a future does not have any registered handler when it completes with an error, it forwards the error to an "uncaught-error handler". This behavior ensures that no error is silently dropped. However, it also means that error handlers should be installed early, so that they are present as soon as a future is completed with an error. The following example demonstrates this potential bug: <pre class="language-dart"><code class="language-dart">var future = getFuture(); Timer(const Duration(milliseconds: 5), () { // The error-handler is not attached until 5 ms after the future has // been received. If the future fails before that, the error is // forwarded to the global error-handler, even though there is code // (just below) to eventually handle the error. future.then((value) { useValue(value); }, onError: (e) { handleError(e); }); }); </code></pre> When registering callbacks, it's often more readable to register the two callbacks separately, by first using <a href="../dart-async/Future/then.html">then</a> with one argument (the value handler) and using a second <a href="../dart-async/Future/catchError.html">catchError</a> for handling errors. Each of these will forward the result that they don't handle to their successors, and together they handle both value and error result. It has the additional benefit of the <a href="../dart-async/Future/catchError.html">catchError</a> handling errors in the <a href="../dart-async/Future/then.html">then</a> value callback too. Using sequential handlers instead of parallel ones often leads to code that is easier to reason about. It also makes asynchronous code very similar to synchronous code: <pre class="language-dart"><code class="language-dart">// Synchronous code. try { int value = foo(); return bar(value); } catch (e) { return 499; } </code></pre> Equivalent asynchronous code, based on futures: <pre class="language-dart"><code class="language-dart">Future<int> asyncValue = Future(foo); // Result of foo() as a future. asyncValue.then((int value) { return bar(value); }).catchError((e) { return 499; }); </code></pre> Similar to the synchronous code, the error handler (registered with <a href="../dart-async/Future/catchError.html">catchError</a>) is handling any errors thrown by either <code>foo</code> or <code>bar</code>. If the error-handler had been registered as the <code>onError</code> parameter of the <code>then</code> call, it would not catch errors from the <code>bar</code> call. Futures can have more than one callback-pair registered. Each successor is treated independently and is handled as if it was the only successor. The order in which the individual successors are completed is undefined. A future may also fail to ever complete. In that case, no callbacks are called. That situation should generally be avoided if possible, unless it's very clearly documented. </section> <section> <dl class="dl-horizontal"> <dt>Available Extensions</dt> <dd><ul class="comma-separated clazz-relationships"> <li><a href="../dart-async/FutureExtensions.html">FutureExtensions</a></li> <li><a href="../dart-js_interop/FutureOfJSAnyToJSPromise.html">FutureOfJSAnyToJSPromise</a></li> <li><a href="../dart-js_interop/FutureOfVoidToJSPromise.html">FutureOfVoidToJSPromise</a></li> </ul></dd> <dt>Annotations</dt> <dd> <ul class="annotation-list clazz-relationships"> <li>@vmIsolateUnsendable</li> </ul> </dd> </dl> </section> <section class="summary offset-anchor" id="constructors"> <h2>Constructors</h2> <dl class="constructor-summary-list"> <dt id="Future" class="callable"> <a href="../dart-async/Future/Future.html">Future</a>(<a href="../dart-async/FutureOr-class.html">FutureOr</a><T> computation()) </dt> <dd> Creates a future containing the result of calling <code>computation</code> asynchronously with <a href="../dart-async/Timer/run.html">Timer.run</a>. <div class="constructor-modifier features">factory</div> </dd> <dt id="Future.delayed" class="callable"> <a href="../dart-async/Future/Future.delayed.html">Future.delayed</a>(<a href="../dart-core/Duration-class.html">Duration</a> duration, [<a href="../dart-async/FutureOr-class.html">FutureOr</a><T> computation()?]) </dt> <dd> Creates a future that runs its computation after a delay. <div class="constructor-modifier features">factory</div> </dd> <dt id="Future.error" class="callable"> <a href="../dart-async/Future/Future.error.html">Future.error</a>(<a href="../dart-core/Object-class.html">Object</a> error, [<a href="../dart-core/StackTrace-class.html">StackTrace</a>? stackTrace]) </dt> <dd> Creates a future that completes with an error. <div class="constructor-modifier features">factory</div> </dd> <dt id="Future.microtask" class="callable"> <a href="../dart-async/Future/Future.microtask.html">Future.microtask</a>(<a href="../dart-async/FutureOr-class.html">FutureOr</a><T> computation()) </dt> <dd> Creates a future containing the result of calling <code>computation</code> asynchronously with <a href="../dart-async/scheduleMicrotask.html">scheduleMicrotask</a>. <div class="constructor-modifier features">factory</div> </dd> <dt id="Future.sync" class="callable"> <a href="../dart-async/Future/Future.sync.html">Future.sync</a>(<a href="../dart-async/FutureOr-class.html">FutureOr</a><T> computation()) </dt> <dd> Returns a future containing the result of immediately calling <code>computation</code>. <div class="constructor-modifier features">factory</div> </dd> <dt id="Future.value" class="callable"> <a href="../dart-async/Future/Future.value.html">Future.value</a>([<a href="../dart-async/FutureOr-class.html">FutureOr</a><T>? value]) </dt> <dd> Creates a future completed with <code>value</code>. <div class="constructor-modifier features">factory</div> </dd> </dl> </section> <section class="summary offset-anchor inherited" id="instance-properties"> <h2>Properties</h2> <dl class="properties"> <dt id="hashCode" class="property inherited"> <a href="../dart-core/Object/hashCode.html">hashCode</a> → <a href="../dart-core/int-class.html">int</a> </dt> <dd class="inherited"> The hash code for this object. <div class="features">no setterinherited</div> </dd> <dt id="runtimeType" class="property inherited"> <a href="../dart-core/Object/runtimeType.html">runtimeType</a> → <a href="../dart-core/Type-class.html">Type</a> </dt> <dd class="inherited"> A representation of the runtime type of the object. <div class="features">no setterinherited</div> </dd> </dl> </section> <section class="summary offset-anchor" id="instance-methods"> <h2>Methods</h2> <dl class="callables"> <dt id="asStream" class="callable"> <a href="../dart-async/Future/asStream.html">asStream</a>() → <a href="../dart-async/Stream-class.html">Stream</a><T> </dt> <dd> Creates a <a href="../dart-async/Stream-class.html">Stream</a> containing the result of this future. </dd> <dt id="catchError" class="callable"> <a href="../dart-async/Future/catchError.html">catchError</a>(<a href="../dart-core/Function-class.html">Function</a> onError, {<a href="../dart-core/bool-class.html">bool</a> test(<a href="../dart-core/Object-class.html">Object</a> error)?}) → <a href="../dart-async/Future-class.html">Future</a><T> </dt> <dd> Handles errors emitted by this <a href="../dart-async/Future-class.html">Future</a>. </dd> <dt id="noSuchMethod" class="callable inherited"> <a href="../dart-core/Object/noSuchMethod.html">noSuchMethod</a>(<a href="../dart-core/Invocation-class.html">Invocation</a> invocation) → dynamic </dt> <dd class="inherited"> Invoked when a nonexistent method or property is accessed. <div class="features">inherited</div> </dd> <dt id="then" class="callable"> <a href="../dart-async/Future/then.html">then</a><R>(<a href="../dart-async/FutureOr-class.html">FutureOr</a><R> onValue(T value), {<a href="../dart-core/Function-class.html">Function</a>? onError}) → <a href="../dart-async/Future-class.html">Future</a><R> </dt> <dd> Register callbacks to be called when this future completes. </dd> <dt id="timeout" class="callable"> <a href="../dart-async/Future/timeout.html">timeout</a>(<a href="../dart-core/Duration-class.html">Duration</a> timeLimit, {<a href="../dart-async/FutureOr-class.html">FutureOr</a><T> onTimeout()?}) → <a href="../dart-async/Future-class.html">Future</a><T> </dt> <dd> Stop waiting for this future after <code>timeLimit</code> has passed. </dd> <dt id="toString" class="callable inherited"> <a href="../dart-core/Object/toString.html">toString</a>() → <a href="../dart-core/String-class.html">String</a> </dt> <dd class="inherited"> A string representation of this object. <div class="features">inherited</div> </dd> <dt id="whenComplete" class="callable"> <a href="../dart-async/Future/whenComplete.html">whenComplete</a>(<a href="../dart-async/FutureOr-class.html">FutureOr</a><void> action()) → <a href="../dart-async/Future-class.html">Future</a><T> </dt> <dd> Registers a function to be called when this future completes. </dd> </dl> </section> <section class="summary offset-anchor inherited" id="operators"> <h2>Operators</h2> <dl class="callables"> <dt id="operator ==" class="callable inherited"> <a href="../dart-core/Object/operator_equals.html">operator ==</a>(<a href="../dart-core/Object-class.html">Object</a> other) → <a href="../dart-core/bool-class.html">bool</a> </dt> <dd class="inherited"> The equality operator. <div class="features">inherited</div> </dd> </dl> </section> <section class="summary offset-anchor" id="static-methods"> <h2>Static Methods</h2> <dl class="callables"> <dt id="any" class="callable"> <a href="../dart-async/Future/any.html">any</a><T>(<a href="../dart-core/Iterable-class.html">Iterable</a><<a href="../dart-async/Future-class.html">Future</a><T>> futures) → <a href="../dart-async/Future-class.html">Future</a><T> </dt> <dd> Returns the result of the first future in <code>futures</code> to complete. </dd> <dt id="doWhile" class="callable"> <a href="../dart-async/Future/doWhile.html">doWhile</a>(<a href="../dart-async/FutureOr-class.html">FutureOr</a><<a href="../dart-core/bool-class.html">bool</a>> action()) → <a href="../dart-async/Future-class.html">Future</a><void> </dt> <dd> Performs an operation repeatedly until it returns <code>false</code>. </dd> <dt id="forEach" class="callable"> <a href="../dart-async/Future/forEach.html">forEach</a><T>(<a href="../dart-core/Iterable-class.html">Iterable</a><T> elements, <a href="../dart-async/FutureOr-class.html">FutureOr</a> action(T element)) → <a href="../dart-async/Future-class.html">Future</a><void> </dt> <dd> Performs an action for each element of the iterable, in turn. </dd> <dt id="wait" class="callable"> <a href="../dart-async/Future/wait.html">wait</a><T>(<a href="../dart-core/Iterable-class.html">Iterable</a><<a href="../dart-async/Future-class.html">Future</a><T>> futures, {<a href="../dart-core/bool-class.html">bool</a> eagerError = false, void cleanUp(T successValue)?}) → <a href="../dart-async/Future-class.html">Future</a><<a href="../dart-core/List-class.html">List</a><T>> </dt> <dd> Waits for multiple futures to complete and collects their results. </dd> </dl> </section> </div>  <div id="dartdoc-sidebar-left" class="sidebar sidebar-offcanvas-left">  <header id="header-search-sidebar" class="hidden-l"> <form class="search-sidebar" role="search"> <input type="text" id="search-sidebar" autocomplete="off" disabled class="form-control typeahead" placeholder="Loading search..."> </form> </header> <ol class="breadcrumbs gt-separated dark hidden-l" id="sidebar-nav"> <li><a href="../index.html">Dart</a></li> <li><a href="../dart-async/dart-async-library.html">dart:async</a></li> <li class="self-crumb">Future<T> class</li> </ol> <h5>dart:async library</h5> <div id="dartdoc-sidebar-left-content"></div> </div> <div id="dartdoc-sidebar-right" class="sidebar sidebar-offcanvas-right"> </div> </main> <footer> Dart 3.5.4 | <a href="https://dart.dev/terms" title="Terms of use">Terms</a> | <a href="https://policies.google.com/privacy" target="_blank" rel="noopener" title="Privacy policy" class="no-automatic-external">Privacy</a> | <a href="https://dart.dev/security" title="Security philosophy and practices">Security</a> <div class="copyright" style="font-size: 0.9em; color: darkgrey; margin-top: 0.5em;"> Except as otherwise noted, this site is licensed under a <a style="color: darkgrey;" href="https://creativecommons.org/licenses/by/4.0/"> Creative Commons Attribution 4.0 International License</a> and code samples are licensed under the <a style="color: darkgrey;" href="https://opensource.org/licenses/BSD-3-Clause" class="no-automatic-external"> 3-Clause BSD License</a> </div> </footer> <script src="../static-assets/highlight.pack.js?v1"></script> <script src="../static-assets/docs.dart.js"></script> <button aria-hidden="true" class="glue-footer__link glue-cookie-notification-bar-control"> Cookies management controls </button> <script src="https://www.gstatic.com/glue/cookienotificationbar/cookienotificationbar.min.js" data-glue-cookie-notification-bar-category="2B"> </script> </body> </html>