
# isolate のプール

デフォルトでは、サーバーは一つの isolate、つまりアプリケーション自身の isolate から応答し、プロセッサーコアを一つ使います。`server.isolates.count` はそれを増やします。各 isolate がアプリケーション全体を実行し、すべてが同じポートを担当します。

変わるのは速度だけではありません。有効にする前に [isolate が複数になると変わること](#isolate-が複数になると変わること) を読んでください。

## 使う理由

isolate は一度に一つのことを行い、プロセッサーコアを一つ使います。ハンドラーが計算をするサーバー (大きな JSON、ハッシュ、画像) は、他のコアが空いているのに、そのコアの限界に達します。isolate を増やせば、それらのコアが使われます。

Tomcat は、Bean を共有するスレッドでこれを行います。Dart の isolate は何も共有しないので、ここでは各 isolate がアプリケーションを自分用に持ちます。そのためコードにロックは要りません。そして、Bean がメモリーに持つものは、isolate ごとに一つずつ持たれることになります。

ほとんどの時間を待って過ごすサーバー、つまりデータベースや別のサービスを待つサーバーには役立ちません。一つの isolate は多くの応答を同時に待てます。できないのは、二つのことを同時に計算することです。まず計測してください。[負荷テスト](../../../docs/load-testing.md) を参照してください。

## 例

```yaml
# lib/resources/application.yml
server:
  isolates:
    count: 4        # または auto: プロセッサーコアごとに一つ
```

```dart
// bin/main.dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

import 'spring_gen/main.spring.dart';

@SpringBootApplication()
void main(List<String> args) => runApplication(args);
```

コードで他に変わるところはありません。最初の isolate は次のようにログを出します。

```text
INFO  Web server started on port 8080 (http)
INFO  Scaling 1 → 4 isolates (server.isolates.count=4)
WARN  Each isolate keeps its own sessions in memory, and a request may reach any isolate: what one keeps the others do not see. Keep it where all of them do (a database, a shared store), or accept one copy per isolate.
INFO  Isolate isolate-1 ready in 0.412 seconds
INFO  Isolate isolate-2 ready in 0.415 seconds
INFO  Isolate isolate-3 ready in 0.431 seconds
INFO  Started neon-books in 0.52 seconds
```

コントローラーは、どの isolate が応答しているかを知ることができます。

```dart
@RestController()
class WhoController {
  WhoController(this.isolate);
  final IsolateInfo isolate;

  @GetMapping('/who')
  String who() => isolate.name; // main、isolate-1、isolate-2 または isolate-3
}
```

## isolate が複数になると変わること

| 対象 | isolate が複数の場合 | すべきこと |
|---|---|---|
| Bean | すべての isolate がアプリケーション全体を実行する。各 Bean は isolate ごとに一つ存在し、Bean がメモリーに持つものはその数だけ持たれる | アプリケーションがメモリーに持つものに isolate の数を掛けて見積もる |
| リクエスト | どの isolate にも届きうる。接続は最初に受け取った isolate のものになり、キープアライブ接続のリクエストはその isolate にとどまる。一つのブラウザーの二つのリクエストに、二つの isolate が応答することがある | このリクエストがメモリーに残したものを、次のリクエストが見つけるとは期待しない |
| メモリー上のセッション | 各 isolate が独自のものを持つ。ある isolate が作ったセッションを次の isolate は知らず、ユーザーはランダムにログアウトされる。`server.session.max-sessions` は isolate ごとに数える | すべての isolate から見える場所にセッションを保つ `HttpSessionRepository` を宣言する。[セッション](../sessions.md#isolate-のプールがある場合) を参照 |
| キャッシュ (`@Cacheable`) | 各 isolate が独自のキャッシュされた値を持つ。値は isolate ごとに一度計算され、`@CacheEvict` はそれを実行した isolate でだけ削除する | しばらく古い値でも構わないところでは受け入れる。そうでなければ isolate の外にあるキャッシュを使う。[メモリ上のキャッシュ](../../spring-boot-starter-cache/in-memory-caches.md#isolate-のプールがある場合) を参照 |
| カウンター、レートリミッター、Bean の任意のフィールド | 自分の isolate が見たものを数える。メモリーに持つ毎分 100 の制限は、isolate ごとに 100 を通す | 共有ストアに保つか、制限を isolate の数で割る |
| `WebSocketSessionRegistry.broadcast` | 送信する isolate に接続しているクライアントに届く。他の isolate のクライアントには届かない | すべての isolate が聞いているもの (メッセージブローカー、データベースの通知) を通して送る |
| サーバー送信イベント | `SseEmitter` は、リクエストを受け取った isolate の中にある。「すべての」エミッターに送る Bean は、自分の isolate のエミッターに送る | 同上 |
| `@Scheduled` メソッド | 最初の isolate でだけ実行されるので、ジョブはアプリケーションで一度実行される | 各 isolate が自分のためにすべきことには `spring.task.scheduling.isolates: all`。[@Scheduled](../../spring-boot-starter-scheduling/scheduled.md#isolate-のプールがある場合) を参照 |
| `ApplicationRunner` と `CommandLineRunner` の Bean、`@PostConstruct`、コンテキストのイベントの `@EventListener` | すべての isolate で一度ずつ実行される。マイグレーション、ウォームアップ、「サーバーが起動しました」というメールが四回起きる | Bean に `@ConditionalOnPrimaryIsolate()` を付けるか、`if (isolate.primary)` を使う |
| バナーと `Started … in` | 最初の isolate が一度だけログに出す。`Started … in` は他の isolate の準備ができたときに出る | なし |
| シグナル (`Ctrl+C`、`SIGTERM`) | `spring.main.register-shutdown-hook: true` のとき、最初の isolate がシグナルを受け取り、自分のコンテキストとともに他の isolate を停止する。他の isolate はフックを登録しない | なし |
| すべての isolate から見える必要のある状態 | アプリケーションの責任: データベース、共有ストア。フレームワークは Bean を同期しない。アプリケーションの中に一つだけ存在しなければならないものには、部品が一つある: 最初の isolate の Bean に、他の isolate が問い合わせる ([`PrimaryIsolate`](../../spring-core-dart/isolates/primary-isolate.md)) | `count` を上げる前に、それに合わせて設計する |
| データベースのコネクションプール | Bean である: isolate ごとにプールが一つ。`spring.datasource.pool.max-size: 10` で isolate が四つなら、データベースでは最大 40 接続になる | プールのサイズを割るか、データベースの上限を上げる |
| `server.max-connections`、`server.max-concurrent-requests` | isolate ごとの値である: サーバー全体では、その値に isolate の数を掛けただけ受け付ける。[過負荷](overload.md) を参照 | isolate ごとの値として設定する |
| `isolateTaskExecutor` | 各 isolate が独自のタスク用の isolate のプールを持つ (`isolate-2-task-1`) | `core-size` に isolate の数を掛けて見積もる |
| アクチュエーターのエンドポイント | `isolates` と `qps` は最初の isolate に問い合わせるので、どの isolate もアプリケーション全体について応答する。その他は、`health` も含め、リクエストを受け取った isolate について応答する。[`isolates` エンドポイント](../../spring-boot-actuator/isolates.md#isolate-のプールがある場合) を参照 | その二つについてはなし。一つの isolate の `health` をアプリケーションのものとして読まない |
| 予期せず終了した isolate | 再び起動される。それが応答していたリクエストは応答を受け取らない。その接続は、VM が isolate を回収するか、クライアントが諦めるまで開いたままになる | クライアントにタイムアウトを持たせる。ログで `ended unexpectedly` を探す |
| Flutter アプリ | プールはない: 設定は警告とともに無視される | なし。[Flutter アプリでは](#flutter-アプリでは) を参照 |
| ホットリロード | リロードがコンテキストを再起動すると、プールもそれとともに停止し、新しいコンテキストが isolate を再び起動する | なし |

プールは、自分に見えるものの名前を挙げます。`IsolateLocalState` を実装する Bean は、プールが最初に isolate を追加するときに一度だけログに出す警告に列挙されます。メモリー上のセッションリポジトリ (`sessions`)、キャッシュスターターのマネージャー、つまりデフォルトのメモリー上のものと `SimpleCacheManager` (`cached values`)、そして `WebSocketSessionRegistry` (`WebSocket sessions`) がこれを実装しています。プールは、どの型で宣言されたかにかかわらず、自分が大きくなる時点で存在する Bean の中からそれらを見つけます。独自の Bean も列挙させることができます。

```dart
@Service()
class LoginAttempts implements IsolateLocalState {
  final _failed = <String, int>{};

  @override
  String get isolateLocalState => 'failed logins';
}
```

```text
WARN  Each isolate keeps its own sessions, failed logins in memory, and a request may reach any isolate: what one keeps the others do not see. Keep it where all of them do (a database, a shared store), or accept one copy per isolate.
```

この警告はエラーではありません。キャッシュは isolate ごとに一つのコピーでもたいてい問題ありませんが、セッションは通常そうはいきません。

## アプリケーションで一度だけ

`@ConditionalOnPrimaryIsolate()` は、Bean を最初の isolate にだけ登録します。

```dart
@Component()
@ConditionalOnPrimaryIsolate()
class Migrations implements ApplicationRunner {
  Migrations(this.db);
  final Database db;

  // isolate ごとに一度ではなく、アプリケーションで一度。
  @override
  Future<void> run(ApplicationArguments args) => db.migrate();
}
```

すべての isolate に必要な Bean の中では、`IsolateInfo` (Bean `isolateInfo`) で判断します。

```dart
@PostConstruct()
void warmUp() {
  cache.load();                       // どの isolate にも自分のキャッシュが必要
  if (isolate.primary) migrate();     // データベースのマイグレーションは一度だけ
}
```

- この条件の付いた Bean は、他の isolate には存在しません。それをコンストラクターで受け取る Bean はそこで失敗し、その isolate は起動しません (`Isolate isolate-1 failed to start`)。両方に条件を付けるか、null 許容型として受け取ってください。
- この条件の付いたコントローラーは、最初の isolate でだけマッピングされます。そのパスへのリクエストを別の isolate が受け取ると、ハンドラーが見つかりません。
- プールがなければ、この条件は常に一致します。

その一つの Bean が知っていることを他の isolate が必要とするときは、その Bean に問い合わせます。最初の isolate の Bean で `PrimaryIsolateHandler` を実装するものが、すべての isolate からの `primaryIsolate.ask(...)` に応答します。[最初の isolate に問い合わせる](../../spring-core-dart/isolates/primary-isolate.md) を参照してください。

## プールの起動

1. **最初の isolate はいつもどおり起動します。** そのサーバーはポートを共有でバインドするので、同じプログラムが再びバインドできます。
2. **プールが他の isolate を起動します。** そのサーバーが待ち受けを始めたときに、すべて同時に起動します。それぞれは新しい isolate で再び起動されたアプリケーションで、引数、プロパティ、プロファイルは同じです。そして自身の構成より優先して次のものが適用されます: 最初の isolate のポート (最初の isolate が `server.port=0` で任意の空きポートを求めた場合も)、バナーなし、起動時の行なし、シャットダウンフックなし。
3. **isolate は、自分の Bean が立ち上がったときにポートに加わります。** 準備のできていない isolate にリクエストが送られることはありません。その後、最初の isolate に知らせ、最初の isolate が `Isolate isolate-1 ready in … seconds` をログに出します。
4. **アプリケーションはそれらを待ちます。** `Started … in`、最初の isolate のランナー、`ApplicationReadyEvent` は、すべての isolate の準備ができるか失敗した後に来ます。二分たっても準備のできない isolate は諦められます。

起動に失敗した isolate はログに記録され (`Isolate isolate-2 failed to start` とエラー)、除外されます。サーバーは残りの isolate で動きます。再試行はされません。

isolate の名前は `isolate-1`、`isolate-2`、… です。最初の isolate は `main` のままです。`IsolateInfo.index` はその番号で、`main` は `0` です。

### アプリケーションは再び起動できなければならない

プールは、`ApplicationLaunch` Bean を通して別の isolate でアプリケーションを起動します。この Bean は、アプリケーションを返すものを渡して実行されたときに存在します。生成された `runApplication(args)` と `runApplicationAsync(args)` はそうします。手で起動するアプリケーションは、それを渡さなければなりません。

```dart
SpringApplication.run(args, hotReload: () => springApplication);
```

これがないと、プールは isolate を追加できず、`The pool of isolates did not start` をログに出し、最初の isolate だけで応答します。

```text
Isolates cannot be added: the application was not started in a way that can be repeated in another isolate. Start it with the generated runApplication(args), or pass what returns it: SpringApplication.run(args, hotReload: () => springApplication).
```

アプリケーションを返すものは別の isolate に渡されるので、その周囲のものを何も使ってはいけません。生成された `() => springApplication` は使っていません。

## ログ

プールは `spring.web.isolates` にログを出します。起動、スケーリングのステップ、失敗のたびに一行が出ます。

| レベル | 行 | タイミング |
|---|---|---|
| `info` | `Scaling 1 → 4 isolates (server.isolates.count=4)` | 起動時、および [スケーリングのステップ](scaling.md) のたびに、その理由とともに |
| `warn` | `Each isolate keeps its own … in memory, …` | 一度だけ。プールが最初に isolate を追加し、いずれかの Bean が `IsolateLocalState` であるとき |
| `info` | `Isolate isolate-1 ready in 0.412 seconds` | そのサーバーが待ち受けを始めた |
| `error` | `Isolate isolate-1 failed to start` | 起動に失敗したか、二分より長くかかった |
| `error` | `The pool of isolates did not start` | `count` の isolate を追加できなかった |
| `error` | `Uncaught error in isolate-1: …` | 何にも捕捉されなかったエラー。スタックトレース付き。isolate は動き続ける |
| `error` | `Isolate isolate-1 ended unexpectedly: starting it again` | 求められていないのに終了した |
| `error` | `Isolate isolate-1 ended unexpectedly, the fourth in a minute: not started again. 3 isolates serve.` | 下記を参照 |
| `info` | `Draining isolate isolate-3` | プールを離れる: スケールダウンのステップで、またはコンテキストが閉じるとき |
| `warn` | `Isolate isolate-3 did not stop within 30 seconds (server.isolates.drain-timeout): stopped anyway` | そのリクエストが時間内に完了しなかった |
| `info` | `Isolate isolate-3 stopped` | 求められたとおりに終了した |
| `info` | `Stopping 3 isolates` | コンテキストが閉じる |

他の isolate も最初の isolate と同じようにログを出します。その行には、`main` の行に `main` があるところに、それぞれの名前が入ります。ロギングスターターのパターンでは `%thread`、デフォルトの行では先頭の `[isolate-2]` です。[isolate](../../spring-core-dart/isolates/index.md#ログでの表示) を参照してください。

各 isolate は独自のロギングを実行します。複数の isolate が同じファイルに書き込むときに、ログファイル (`logging.file.name`) とそのローテーションが機能するかどうかは検証されていません。

## isolate が終了したとき

isolate は、求められていないのに終了することがあります。たとえば、アプリケーションのコードの `Isolate.exit()` によってです。

- プールはそれをログに記録し、同じ名前の isolate を再び起動します。
- **実行中のリクエストは応答を受け取りません。** その接続は、VM が isolate を回収するか、クライアントが諦めるまで開いたままになります。その間も他の isolate は応答を続けます。
- それがメモリーに持っていたものは失われます。セッションもキャッシュもです。
- **一分以内に終了した四つ目の isolate は、再び起動されません。** 壊れたアプリケーションが再起動を繰り返さないようにするためです。その後プールは、スケーリングされるかアプリケーションが再起動するまで、少ない isolate で応答します。

ハンドラーが投げたエラーは isolate を終了させません。isolate が一つのときと同じく、`500` で応答されます。

## 停止

プールはコンテキストとともに、最初の isolate のサーバーより先に停止します。`Stopping 3 isolates` の後、各 isolate がドレインされます。ドレイン中の isolate は接続の受け付けを止め、停止するアプリケーションと同じようにリクエストを完了させ ([シャットダウン](shutdown.md) を参照)、`@PreDestroy` メソッドを実行して終了します。`server.isolates.drain-timeout` を過ぎても終了していない isolate は、それでも停止されます。

## Flutter アプリでは

プールはサーバープログラムのためのものです。サーバーを実行する Flutter アプリは、一つの isolate のままです。プールの isolate はアプリケーション全体を実行することになりますが、Flutter アプリのウィジェット、アセット、プラグインは最初の isolate にしか存在しないからです。`server.isolates.*` が設定されていると、アプリは次の警告をログに出し、設定がないときと同じように起動します。

```text
server.isolates is ignored in a Flutter app: an isolate of the pool runs the whole application, and the widgets, the assets and the plugins of a Flutter app exist in its first isolate only.
```

Flutter アプリでの重い処理には [タスクエグゼキューター](../../spring-core-dart/isolates/task-executor.md) を使ってください。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `server.isolates.count` | 数値、または `auto` | `1` | 起動時に応答する isolate の数。`auto`: プロセッサーコアごとに一つ。`1`: アプリケーション自身の isolate だけ。数値でないその他の値は `1` として扱われる |
| `server.isolates.drain-timeout` | `Duration` | `30s` | プールを離れる isolate が、それでも停止されるまでにリクエストを完了させてよい時間 |

`server.isolates.scaling`、`min`、`max` とスケーリングのポリシーのキーは [isolate のスケーリング](scaling.md) にあります。

`count: 1`、`scaling: manual` で、1 より大きい `max` がなければ、プールはまったくありません。`serverIsolatePool` Bean はなく、ポートは共有されません。

## Spring (Java) との対応

Spring に対応するものはありません。Tomcat のワーカースレッド (`server.tomcat.threads.*`) は一つのヒープと Bean を共有します。セッション、キャッシュ、カウンターはどのスレッドにとっても同じものです。Java でいちばん近いのは、ロードバランサーの背後にあるアプリケーションの複数のインスタンスです。上の表の問いは、そこで問われるものと同じです。

## 関連項目

- [isolate のスケーリング](scaling.md)
- [過負荷](overload.md)
- [毎秒のリクエスト数](qps.md)
- [isolate](../../spring-core-dart/isolates/index.md)
- [isolate の負荷](../../spring-core-dart/isolates/load.md)
- [最初の isolate に問い合わせる](../../spring-core-dart/isolates/primary-isolate.md)
- [条件: @ConditionalOnPrimaryIsolate](../../spring-boot-dart/conditions.md#conditionalonprimaryisolate)
- [セッション](../sessions.md)
- [シャットダウン](shutdown.md)
- [負荷テスト](../../../docs/load-testing.md)
- [すべてのプロパティ](../properties.md)
