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
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 |
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 |
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.
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). To ask that isolate from the others, see Asking the first isolate.
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:
[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:
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.
The classes are in spring_core_dart (package:spring_core_dart/core.dart) and work without Spring Boot:
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:
IsolateTaskExecutor,submitandsubmitWith, what crosses to another isolate, the pool and its properties. - The load of the isolates:
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:
PrimaryIsolateandPrimaryIsolateHandler, for what must exist once for the application.