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

See also