Asking the first isolate

With a pool of server isolates a request may reach any of them, and every isolate has its own beans. Some things must exist once all the same: a sequence of numbers, a switch, the total of what every isolate counted. Their owner lives in the application's first isolate, as a PrimaryIsolateHandler bean, and the others ask it through PrimaryIsolate, the bean primaryIsolate.

Why

@ConditionalOnPrimaryIsolate and IsolateInfo.primary keep a bean or a step to the first isolate. That is enough for what only acts: a scheduled job, a migration. It is not enough when a request needs what that bean knows, because the request may be in another isolate, where the bean either does not exist or is another copy with other values.

PrimaryIsolate closes that gap: the code that asks is the same in every isolate, and the answer always comes from the one bean in the first.

The framework uses it for its own things that exist once: the pool of isolates (scaling from any isolate), the load of every isolate, and the requests per second added up from all of them.

Example

import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

@Component()
class Tickets implements PrimaryIsolateHandler {
  var _next = 0;

  @override
  String get id => 'tickets.next';

  // Runs in the first isolate only: one sequence for the application.
  @override
  Object? handle(Object? request) => ++_next;
}

@RestController()
class TicketController {
  TicketController(this.primary);
  final PrimaryIsolate primary;

  // Whichever isolate takes the request, the number comes from the first.
  @PostMapping('/tickets')
  Future<int> next() async => await primary.ask('tickets.next') as int;
}

With a counter in a field of the controller instead, four isolates would each hand out 1, 2, 3.

How a question travels

Where ask is called What happens
In the first isolate, or in an application without a pool The question goes straight to the PrimaryIsolateHandler bean of that id: a local call
In another isolate of the server's pool The question is sent to the first isolate, the handler answers there, and the answer comes back

The pool sets this up in each isolate it starts, before the application starts there. So a bean may ask as soon as it exists, in its @PostConstruct method too.

ask(id, [request]) completes with the answer. It has no timeout: it waits until the first isolate has answered.

A handler of your own

A handler is a bean that implements PrimaryIsolateHandler:

Member Meaning
id The name questions are sent under, one per handler
handle(request) Answers in the first isolate. It may return a value or a Future
@Component()
class Maintenance implements PrimaryIsolateHandler {
  var _on = false;

  @override
  String get id => 'maintenance';

  // {"set": true} switches it; anything else only reads.
  @override
  Object? handle(Object? request) {
    if (request case {'set': final bool on}) {
      _on = on;
    }
    return _on;
  }
}

// In any isolate:
final on = await primary.ask('maintenance') as bool;
await primary.ask('maintenance', {'set': true});

What crosses

The request and the answer cross isolates as JSON values: numbers, text, booleans, null, lists and maps of them.

Without a pool nothing crosses: the call is local and the object itself is handed over. So a request that is an object of your own works with one isolate and fails with a pool. Write the request and the answer as JSON values from the start, and test with server.isolates.count=2.

Errors

In the first isolate, or without a pool In another isolate
No handler has that id A StateError: No PrimaryIsolateHandler bean answers "tickets.next" in main A PrimaryIsolateException with that text
The handler throws The handler's own error, with its type (FormatException) A PrimaryIsolateException: the error as text (message)

An error cannot cross as an object, so from another isolate it arrives as its text. on FormatException catches in the first isolate and not in the others. Either catch PrimaryIsolateException as well, or let the handler answer with a value that says what went wrong.

The handlers of the framework

Id Bean Answers
isolates.loads (IsolateLoadsHandler.handlerId) isolateLoadsHandler, spring_boot_dart Every isolate's load as JSON rows, the isolates of the pool asked just before
isolates.scale (ServerIsolatePool.scaleHandlerId) the web server's pool A scaling step; the request is {to, reason}. Use the IsolateScaler bean, which sends it
web.qps (RequestRates.handlerId) requestRates, with the web starter's debug feature qps The last window of requests per second as JSON; with the request now, the window ended at this moment

What it is for, and what not

It is the one place inside the application for state that must exist once. That place is one isolate's memory, which sets its limits:

Without a pool none of this costs anything: ask is a call to a bean. An application written this way runs unchanged with one isolate, in a test, in a Flutter app, and in a browser.

Without Spring Boot

PrimaryIsolate is in spring_core_dart (package:spring_core_dart/core.dart) and takes its handlers:

final primary = PrimaryIsolate([Tickets()]);
final ticket = await primary.ask('tickets.next') as int;

With Spring Boot the primaryIsolate bean has every PrimaryIsolateHandler bean; it is left out when the application declares its own PrimaryIsolate.

In Spring (Java)

Spring has no counterpart: a JVM's threads share their beans, so a singleton is already the one place. Here a singleton is one per isolate, and this is how one of them is made the place for all.

See also