
# Isolates

An isolate is how Dart runs code in parallel: a piece of the program with its own memory and its own event loop, doing one thing at a time. A Spring for Dart application runs in one isolate, `main`, unless you ask for more. This section is about asking for more, and about seeing what the isolates do.

## Why

One isolate uses one processor core. A server on an eight-core machine that answers from one isolate leaves seven cores idle, and one long computation (parsing megabytes of JSON, resizing an image) stops every other request, or every frame of an app, until it ends.

More isolates use the other cores. The price is that they share nothing, and that is the difference from Java a developer must know first:

| | A Java thread | A Dart isolate |
|---|---|---|
| Memory | Shares the heap with the other threads | Has its own; nothing is shared |
| A singleton bean | One object, seen by every thread | One object per isolate that runs the application |
| Passing data | A reference | A copy: the function, its argument and its result are copied |
| Protecting state | Locks, `synchronized`, concurrent collections | Nothing to protect: no other isolate can reach it |
| State all of them must see | A field of a bean | Outside the isolates: a database, a shared store |

So code is never interrupted by another thread, and no lock is needed. And a counter in a field of a bean counts what its own isolate did, not what the application did.

## Example

```dart
import 'package:spring_boot_dart/spring_boot_dart.dart';

@Component()
class Migrations {
  Migrations(this.isolate);
  final IsolateInfo isolate;

  // Runs in every isolate that runs the application; migrates in one.
  @PostConstruct()
  void run() {
    if (isolate.primary) migrate();
  }
}
```

With one isolate, the default, `isolate.primary` is always `true` and the code above does what it did before.

## The isolates of an application

| Name in the logs | Kind | Started by | What runs in it |
|---|---|---|---|
| `main` | `main` | the program | The whole application. The only isolate by default, and the primary one always |
| `isolate-1`, `isolate-2`, … | `server` | the web server's pool, with `server.isolates.count` above one | The whole application again, with its own beans, on the same port. See [A pool of isolates](../../spring-boot-starter-web/server/isolates.md) |
| `task-1`, `task-2`, … | `task` | the `IsolateTaskExecutor`, at its first task | One function at a time, with its argument. No beans. See [The task executor](task-executor.md) |

An isolate of the server's pool has a task executor of its own; its isolates carry both names: `isolate-2-task-1`.

An isolate the application starts itself (`Isolate.run`, `compute`) is none of these. The framework does not know about it: a compiled program cannot list its isolates. `IsolateLoads.track` shows it in the task manager while it runs; see [The load of the isolates](load.md).

## IsolateInfo

`IsolateInfo` tells the code which isolate it runs in. With Spring Boot it is the bean `isolateInfo`; without, read `IsolateInfo.current`.

| Member | Meaning |
|---|---|
| `name` | The isolate's name in the logs: `main`, or `isolate-2` in a pool |
| `index` | Its number in the pool; `0` for the primary |
| `primary` | Whether it is the first isolate of the application: the one that started the others, and the only one without a pool |
| `IsolateInfo.current` | The isolate this code runs in. A pool sets it in each isolate it starts, before the application starts there |

Use `primary` for work that must happen once for the application and not once per isolate: a scheduled job, a data migration, a warm-up. To keep a whole bean to the primary isolate, put `@ConditionalOnPrimaryIsolate()` on it (see [Conditions](../../spring-boot-dart/conditions.md#conditionalonprimaryisolate)). To ask that isolate from the others, see [Asking the first isolate](primary-isolate.md).

`IsolateInfo.current` is a static field, and each isolate has its own statics. In an isolate you start yourself nobody has set it: it is the default there (`main`, primary), whatever the isolate is.

## What each platform can do

| | Dart VM, AOT executable (a server, a tool) | Flutter on a phone or a desktop | A browser |
|---|---|---|---|
| The isolate of the application | `main` | `main` | `main`, the only one there is |
| The web server's pool (`server.isolates.*`) | Yes | No: the setting is ignored with a warning, and the server stays in the app's isolate | No server: the web starter's module is not in a browser build |
| `IsolateTaskExecutor` | A pool of isolates | A pool of isolates, so heavy work leaves the isolate that draws | No isolate can be started: the task runs in the calling isolate, in a later turn of its event loop, with the same API |
| The load of `main` (`IsolateLoadSampler`) | Lag, busy share, and the resident memory of the process | The same | Lag and busy share; the JavaScript heap in use where the browser tells it (`performance.memory`, Chromium), no memory elsewhere |
| The engine's threads in the task manager | None: no engine | `raster`, `platform`, `io`, with the Flutter starter's task manager | `raster` only |

A Flutter app cannot run its beans again in another isolate: its widgets, its assets and its plugins exist in the first isolate only. That is why the server's pool is for server programs.

## In the logs

Every isolate has a name, and the logs show it.

Without a logging backend, a line written in another isolate than the application's first starts with the isolate's name:

```text
[isolate-2] [neon.checkout] INFO: paid 12.5
[task-1] [neon.reports] WARNING: 3 rows skipped
```

Lines of `main` are as before: `[neon.checkout] INFO: paid 12.5`.

With `spring_boot_starter_logging`, `%thread` (or `%t`) in a pattern is the isolate's name, and the default console line has it:

```text
2026-10-23T21:08:01.580Z  INFO 4711 --- [shop] [neon] [      isolate-2] neon.checkout                            : paid 12.5 {order=1}
```

An isolate of the task executor does not run the application, so it has no logging configuration: what a task logs is written in the first form, also when the application uses the logging starter.

## The beans

`spring_boot_dart` declares the beans of this section, each left out when the application declares its own: `isolateInfo`, `isolateLoadSampler`, `isolateTaskExecutor`, `isolateLoads`, `isolateReports` and `primaryIsolate`. See [Built-in beans](../../spring-boot-dart/built-in-beans.md#isolates).

The classes are in `spring_core_dart` (`package:spring_core_dart/core.dart`) and work without Spring Boot:

```dart
final executor = IsolateTaskExecutor();
final sum = await executor.submitWith(total, numbers);
await executor.shutdown();
```

## In Spring (Java)

Spring has no counterpart to `IsolateInfo`: its beans share one JVM and its threads. `IsolateTaskExecutor` stands where `ThreadPoolTaskExecutor` does, and the server's pool where Tomcat's worker threads do, with the one difference of the table above: nothing is shared.

## Pages

- [The task executor](task-executor.md): `IsolateTaskExecutor`, `submit` and `submitWith`, what crosses to another isolate, the pool and its properties.
- [The load of the isolates](load.md): `IsolateLoads`, the rows of the task manager, how lag and busy are measured and what they cannot tell, `track`, reports from every isolate.
- [Asking the first isolate](primary-isolate.md): `PrimaryIsolate` and `PrimaryIsolateHandler`, for what must exist once for the application.

## See also

- [A pool of isolates for the web server](../../spring-boot-starter-web/server/isolates.md)
- [Scaling the isolates](../../spring-boot-starter-web/server/scaling.md)
- [The `isolates` endpoint of the actuator](../../spring-boot-actuator/isolates.md)
- [The task manager of a Flutter app](../../spring-boot-starter-flutter/isolates.md)
- [Conditions: @ConditionalOnPrimaryIsolate](../../spring-boot-dart/conditions.md#conditionalonprimaryisolate)
- [SpringLog](../logging/spring-log.md)
