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 |
- The bean exists in every isolate, and only the first isolate's is asked. The copies in the other isolates are never called through
ask; their fields stay as they were made. Put@ConditionalOnPrimaryIsolate()on the handler to have no copies at all. - Give each handler its own id. Of two handlers with one id, the first found answers.
- A handler that answers without awaiting is not interrupted. An isolate does one thing at a time, so
++_nextabove is one sequence without a lock. A handler that awaits lets other questions in at eachawait. - Do not reach the handler another way. A bean that takes
Ticketsand calls it directly gets the copy of its own isolate.
@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:
- It is gone when the application stops, and it is not shared between several instances of the application. What must survive a restart or be seen by another process belongs in a database or a shared store.
- Every question is work for the first isolate, which serves requests too. A handler that every request asks makes the first isolate the limit of the whole pool: the pool was there to remove that limit. Ask rarely: take numbers in blocks, read a switch once in a while, keep the answer.
- The first isolate is never removed from the pool, so what it keeps survives scaling up and down.
- Only isolates that run the application can ask. A task of the task executor and an isolate you start yourself have no beans and no way to the first isolate. Ask before you submit the task, and give it the answer.
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.