Dart supports concurrent programming with async-await, isolates, and classes such as Future and Stream. This page gives an overview of async-await, Future, and Stream, but it’s mostly about isolates.

Within an app, all Dart code runs in an isolate. Each Dart isolate has a single thread of execution and shares no mutable objects with other isolates. To communicate with each other, isolates use message passing. Many Dart apps use only one isolate, the main isolate. You can create additional isolates to enable parallel code execution on multiple processor cores.

Although Dart’s isolate model is built with underlying primitives such as processes and threads that the operating system provides, the Dart VM’s use of these primitives is an implementation detail that this page doesn’t discuss.

If you’re already familiar with Future, Stream, and async-await, then you can skip ahead to the isolates section.

The Dart language and libraries use Future and Stream objects to represent values to be provided in the future. For example, a promise to eventually provide an int value is typed as Future. A promise to provide a series of int values has the type Stream.

As another example, consider the dart:io methods for reading files. The synchronous File method readAsStringSync() reads a file synchronously, blocking until the file is either fully read or an error occurs. The method then either returns an object of type String or throws an exception. The asynchronous equivalent, readAsString(), immediately returns an object of type Future. At some point in the future, the Future completes with either a string value or an error.

It matters whether a method is synchronous or asynchronous because most apps need to do more than one thing at a time.

Asynchronous computations are often the result of performing computations outside of the current Dart code; this includes computations that don’t complete immediately, and where you aren’t willing to block your Dart code waiting for the result. For example, an app might start an HTTP request, but need to update its display or respond to user input before the HTTP request completes. Asynchronous code helps apps stay responsive.

These scenarios include operating system calls like non-blocking I/O, performing an HTTP request, or communicating with a browser. Other scenarios include waiting for computations performed in another Dart isolate as described below, or maybe just waiting for a timer to trigger. All of these processes either run in a different thread, or are handled by the operating system or the Dart runtime, which allows Dart code to run concurrently with the computation.

The async and await keywords provide a declarative way to define asynchronous functions and use their results.

Here’s an example of some synchronous code that blocks while waiting for file I/O:

Here’s similar code, but with changes (highlighted) to make it asynchronous:

The main() function uses the await keyword in front of _readFileAsync() to let other Dart code (such as event handlers) use the CPU while native code (file I/O) executes. Using await also has the effect of converting the Future returned by _readFileAsync() into a String. As a result, the contents variable has the implicit type String.

info Note: The await keyword works only in functions that have async before the function body.

As the following figure shows, the Dart code pauses while readAsString() executes non-Dart code, in either the Dart virtual machine (VM) or the operating system (OS). Once readAsString() returns a value, Dart code execution resumes.

If you’d like to learn more about using async, await, and futures, visit the asynchronous programming codelab.

Most modern devices have multi-core CPUs. To take advantage of multiple cores, developers sometimes use shared-memory threads running concurrently. However, shared-state concurrency is error prone and can lead to complicated code.

Instead of threads, all Dart code runs inside of isolates. Each isolate has its own memory heap, ensuring that none of the state in an isolate is accessible from any other isolate. No shared state between isolates means concurrency complexities like mutexes or locks and data races won’t occur in Dart. That said, isolates don’t prevent race conditions all together.

Using isolates, your Dart code can perform multiple independent tasks at once, using additional processor cores if they’re available. Isolates are like threads or processes, but each isolate has its own memory and a single thread running an event loop.

info Platform note: Only the Dart Native platform implements isolates. To learn more about the Dart Web platform, see the Concurrency on the web section.

You often don’t need to think about isolates at all. Dart programs run in the main isolate by default. It’s the thread where a program starts to run and execute, as shown in the following figure:

Even single-isolate programs can execute smoothly. Before continuing to the next line of code, these apps use async-await to wait for asynchronous operations to complete. A well-behaved app starts quickly, getting to the event loop as soon as possible. The app then responds to each queued event promptly, using asynchronous operations as necessary.

As the following figure shows, every isolate starts by running some Dart code, such as the main() function. This Dart code might register some event listeners—to respond to user input or file I/O, for example. When the isolate’s initial function returns, the isolate stays around if it needs to handle events. After handling the events, the isolate exits.

In a client app, the main isolate’s event queue might contain repaint requests and notifications of tap and other UI events. For example, the following figure shows a repaint event, followed by a tap event, followed by two repaint events. The event loop takes events from the queue in first in, first out order.

Event handling happens on the main isolate after main() exits. In the following figure, after main() exits, the main isolate handles the first repaint event. After that, the main isolate handles the tap event, followed by a repaint event.

If a synchronous operation takes too much processing time, the app can become unresponsive. In the following figure, the tap-handling code takes too long, so subsequent events are handled too late. The app might appear to freeze, and any animation it performs might be jerky.

In client apps, the result of a too-lengthy synchronous operation is often janky (non-smooth) UI animation. Worse, the UI might become completely unresponsive.

If your app’s UI becomes unresponsive due to a time-consuming computation—parsing a large JSON file, for example—consider offloading that computation to a worker isolate, often called a background worker. A common case, shown in the following figure, is spawning a simple worker isolate that performs a computation and then exits. The worker isolate returns its result in a message when the worker exits.

Each isolate message can deliver one object, which includes anything that’s transitively reachable from that object. Not all object types are sendable, and the send fails if any transitively reachable object is unsendable. For example, you can send an object of type List only if none of the objects in the list is unsendable. If one of the objects is, say, a Socket, then the send fails because sockets are unsendable.

For information on the kinds of objects that you can send in messages, see the API reference documentation for the send() method.

A worker isolate can perform I/O (reading and writing files, for example), set timers, and more. It has its own memory and doesn’t share any state with the main isolate. The worker isolate can block without affecting other isolates.

This section discusses some examples that use the Isolate API to implement isolates.

These examples implement a main isolate that spawns a simple worker isolate. Isolate.run() simplifies the steps behind setting up and managing worker isolates:

Flutter note: If you’re using Flutter, you can use Flutter’s compute function instead of Isolate.run(). On the web, the compute function falls back to running the specified function on the current event loop. Use Isolate.run() when targeting native platforms only, for a more ergonomic API.

The main isolate contains the code that spawns a new isolate:

The spawned isolate executes the function passed as the first argument, _readAndParseJson:

Isolate.run() spawns an isolate, the background worker, while main() waits for the result.

The spawned isolate executes the argument passed to run(): the function _readAndParseJson().

Isolate.run() takes the result from return and sends the value back to the main isolate, shutting down the worker isolate.

The worker isolate transfers the memory holding the result to the main isolate. It does not copy the data. The worker isolate performs a verification pass to ensure the objects are allowed to be transferred.

_readAndParseJson() is an existing, asynchronous function that could just as easily run directly in the main isolate. Using Isolate.run() to run it instead enables concurrency. The worker isolate completely abstracts the computations of _readAndParseJson(). It can complete without blocking the main isolate.

The result of Isolate.run() is always a Future, because code in the main isolate continues to run. Whether the computation the worker isolate executes is synchronous or asynchronous doesn’t impact the main isolate, because it’s running concurrently either way.

For the complete program, check out the send_and_receive.dart sample.

You can also create a simple worker isolate with run() using a function literal, or closure, directly in the main isolate.

This example accomplishes the same as the previous. A new isolate spawns, computes something, and sends back the result.

However, now the isolate sends a closure. Closures are less limited than typical named functions, both in how they function and how they’re written into the code. In this example, Isolate.run() executes what looks like local code, concurrently. In that sense, you can imagine run() to work like a control flow operator for “run in parallel”.

Isolate.run() abstracts a handful of lower-level, isolate-related API to simplify isolate management:

You can use these primitives directly for more granular control over isolate functionality. For example, run() shuts down its isolate after returning a single message. What if you want to allow multiple messages to pass between isolates? You can set up your own isolate much the same way run() is implemented, just utilizing the send() method of SendPort in a slightly different way.

One common pattern, which the following figure shows, is for the main isolate to send a request message to the worker isolate, which then sends one or more reply messages.

Check out the long_running_isolate.dart sample, which shows how to spawn a long-running isolate that receives and sends messages multiple times between isolates.

When an isolate calls Isolate.spawn(), the two isolates have the same executable code and are in the same isolate group. Isolate groups enable performance optimizations such as sharing code; a new isolate immediately runs the code owned by the isolate group. Also, Isolate.exit() works only when the isolates are in the same isolate group.

In some special cases, you might need to use Isolate.spawnUri(), which sets up the new isolate with a copy of the code that’s at the specified URI. However, spawnUri() is much slower than spawn(), and the new isolate isn’t in its spawner’s isolate group. Another performance consequence is that message passing is slower when isolates are in different groups.

Flutter note: Flutter doesn’t support Isolate.spawnUri().

All Dart apps can use async-await, Future, and Stream for non-blocking, interleaved computations. The Dart web platform, however, does not support isolates. Dart web apps can use web workers to run scripts in background threads similar to isolates. Web workers’ functionality and capabilities differ somewhat from isolates, though.

For instance, when web workers send data between threads, they copy the data back and forth. Data copying can be very slow, though, especially for large messages. Isolates do the same, but also provide APIs that can more efficiently transfer the memory that holds the message instead.

Creating web workers and isolates also differs. You can only create web workers by declaring a separate program entrypoint and compiling it separately. Starting a web worker is similar to using Isolate.spawnUri to start an isolate. You can also start an isolate with Isolate.spawn, which requires fewer resources because it reuses some of the same code and data as the spawning isolate. Web workers don’t have an equivalent API.