
# 最初の isolate に問い合わせる

サーバーの isolate のプールがある場合、リクエストはどの isolate にも届く可能性があり、すべての isolate が独自の Bean を持ちます。それでも、一つだけ存在しなければならないものがあります。番号の連番、スイッチ、すべての isolate が数えたものの合計などです。その持ち主は、`PrimaryIsolateHandler` Bean として、アプリケーションの最初の isolate にいます。ほかの isolate は、`PrimaryIsolate`、つまり Bean `primaryIsolate` を通して問い合わせます。

## 使う理由

`@ConditionalOnPrimaryIsolate` と `IsolateInfo.primary` は、Bean やステップを最初の isolate だけに置きます。スケジュールされたジョブやマイグレーションのように、動作するだけのものには、それで十分です。しかし、リクエストがその Bean の知っていることを必要とする場合には、十分ではありません。リクエストは別の isolate にあるかもしれず、そこではその Bean が存在しないか、別の値を持つ別のコピーであるためです。

`PrimaryIsolate` はその隙間を埋めます。問い合わせるコードはすべての isolate で同じで、応答は常に、最初の isolate にある一つの Bean から来ます。

フレームワークは、一つだけ存在する自分自身のものにこれを使います。isolate のプール (どの isolate からでもスケーリングできる)、すべての isolate の負荷、すべての isolate から合計した毎秒のリクエスト数です。

## 例

```dart
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';

  // 最初の isolate だけで動く: アプリケーションで一つの連番。
  @override
  Object? handle(Object? request) => ++_next;
}

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

  // どの isolate がリクエストを受け取っても、番号は最初の isolate から来る。
  @PostMapping('/tickets')
  Future<int> next() async => await primary.ask('tickets.next') as int;
}
```

代わりにコントローラーのフィールドにカウンターを置くと、4 つの isolate がそれぞれ 1、2、3 を配ることになります。

## 問い合わせの流れ

| `ask` が呼び出される場所 | 起きること |
|---|---|
| 最初の isolate、またはプールのないアプリケーション | 問い合わせは、その id の `PrimaryIsolateHandler` Bean に直接渡る: ローカルな呼び出し |
| サーバーのプールのほかの isolate | 問い合わせは最初の isolate に送られ、ハンドラーがそこで応答し、応答が戻ってくる |

プールは、起動する各 isolate で、アプリケーションがそこで起動する前にこれを準備します。そのため Bean は、存在した時点から問い合わせることができます。`@PostConstruct` メソッドの中でも同じです。

`ask(id, [request])` は応答で完了します。タイムアウトはありません。最初の isolate が応答するまで待ちます。

## 独自のハンドラー

ハンドラーは、`PrimaryIsolateHandler` を実装する Bean です。

| メンバー | 意味 |
|---|---|
| `id` | 問い合わせを送るときの名前。ハンドラーごとに一つ |
| `handle(request)` | 最初の isolate で応答する。値または `Future` を返せる |

- **Bean はすべての isolate に存在し、問い合わせを受けるのは最初の isolate のものだけです。** ほかの isolate のコピーが `ask` を通して呼び出されることはなく、そのフィールドは作られたときのままです。コピーをまったく持たないようにするには、ハンドラーに `@ConditionalOnPrimaryIsolate()` を付けます。
- **各ハンドラーに独自の id を付けます。** 同じ id のハンドラーが二つあると、最初に見つかったものが応答します。
- **await せずに応答するハンドラーは、割り込まれません。** isolate は一度に一つのことをするので、上の `++_next` はロックなしで一つの連番になります。await するハンドラーは、`await` のたびにほかの問い合わせを通します。
- **別の方法でハンドラーに届かないでください。** `Tickets` を受け取って直接呼び出す Bean は、自分の isolate のコピーを得ます。

```dart
@Component()
class Maintenance implements PrimaryIsolateHandler {
  var _on = false;

  @override
  String get id => 'maintenance';

  // {"set": true} は切り替える。それ以外は読むだけ。
  @override
  Object? handle(Object? request) {
    if (request case {'set': final bool on}) {
      _on = on;
    }
    return _on;
  }
}

// どの isolate でも:
final on = await primary.ask('maintenance') as bool;
await primary.ask('maintenance', {'set': true});
```

## isolate を越えるもの

リクエストと応答は、JSON の値として isolate を越えます: 数値、テキスト、真偽値、`null`、それらのリストとマップです。

**プールがなければ、何も isolate を越えません**: 呼び出しはローカルで、オブジェクトそのものが渡されます。そのため、独自のオブジェクトであるリクエストは、isolate が一つのときは動き、プールがあると失敗します。リクエストと応答は最初から JSON の値として書き、`server.isolates.count=2` でテストしてください。

## エラー

| | 最初の isolate、またはプールなし | ほかの isolate |
|---|---|---|
| その id のハンドラーがない | `StateError`: `No PrimaryIsolateHandler bean answers "tickets.next" in main` | そのテキストを持つ `PrimaryIsolateException` |
| ハンドラーがスローする | ハンドラー自身のエラー。型 (`FormatException`) を保つ | `PrimaryIsolateException`: テキストとしてのエラー (`message`) |

エラーはオブジェクトとして isolate を越えられないため、ほかの isolate からはテキストとして届きます。`on FormatException` は最初の isolate では捕捉し、ほかの isolate では捕捉しません。`PrimaryIsolateException` も捕捉するか、何が問題だったかを示す値でハンドラーが応答するようにしてください。

## フレームワークのハンドラー

| Id | Bean | 応答 |
|---|---|---|
| `isolates.loads` (`IsolateLoadsHandler.handlerId`) | `isolateLoadsHandler`、`spring_boot_dart` | すべての isolate の [負荷](load.md) を JSON の行として。プールの isolate には直前に問い合わせる |
| `isolates.scale` (`ServerIsolatePool.scaleHandlerId`) | Web サーバーのプール | スケーリングのステップ。リクエストは `{to, reason}`。これを送る [`IsolateScaler`](../../spring-boot-starter-web/server/scaling.md) Bean を使う |
| `web.qps` (`RequestRates.handlerId`) | `requestRates`。Web スターターのデバッグ機能 [`qps`](../../spring-boot-starter-web/server/qps.md) がある場合 | 毎秒のリクエスト数の最後のウィンドウを JSON として。リクエストが `now` の場合は、この瞬間に終わったウィンドウ |

## 向いていること、向いていないこと

これは、一つだけ存在しなければならない状態のための、アプリケーション内の唯一の場所です。その場所は一つの isolate のメモリーであり、それが限界を決めます。

- **アプリケーションが停止すると消えます。** また、アプリケーションの複数のインスタンスの間では共有されません。再起動の後も残る必要があるもの、別のプロセスから見える必要があるものは、データベースまたは共有ストアに置くべきです。
- **すべての問い合わせは、最初の isolate の作業になります。** 最初の isolate はリクエストも処理します。すべてのリクエストが問い合わせるハンドラーは、最初の isolate をプール全体の限界にします。プールは、その限界をなくすためにあったはずです。問い合わせはまれにしてください。番号はブロック単位で受け取り、スイッチはときどき読み、応答は保持します。
- **最初の isolate はプールから削除されません。** そのため、そこに持つものは、スケールアップとスケールダウンの後も残ります。
- **問い合わせできるのは、アプリケーションを実行する isolate だけです。** [タスクエグゼキューター](task-executor.md) のタスクと、自分で起動した isolate には、Bean も最初の isolate への経路もありません。タスクを submit する前に問い合わせ、その応答をタスクに渡してください。

プールがなければ、このどれにもコストはかかりません。`ask` は Bean の呼び出しです。この方法で書かれたアプリケーションは、isolate が一つでも、テストでも、Flutter アプリでも、ブラウザーでも、変更なしで動きます。

## Spring Boot なしで使う

`PrimaryIsolate` は `spring_core_dart` (`package:spring_core_dart/core.dart`) にあり、ハンドラーを受け取ります。

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

Spring Boot では、`primaryIsolate` Bean がすべての `PrimaryIsolateHandler` Bean を持ちます。アプリケーションが独自の `PrimaryIsolate` を宣言すると、除外されます。

## Spring (Java) との対応

Spring に対応するものはありません。JVM のスレッドは Bean を共有するので、シングルトンがすでにその唯一の場所です。ここではシングルトンは isolate ごとに一つあり、これは、そのうちの一つを全体のための場所にする方法です。

## 関連項目

- [isolate](index.md)
- [isolate の負荷](load.md)
- [Web サーバーの isolate のプール](../../spring-boot-starter-web/server/isolates.md)
- [isolate のスケーリング](../../spring-boot-starter-web/server/scaling.md)
- [条件: @ConditionalOnPrimaryIsolate](../../spring-boot-dart/conditions.md#conditionalonprimaryisolate)
- [組み込みの Bean](../../spring-boot-dart/built-in-beans.md#isolate)
