
# タスクエグゼキューター

`IsolateTaskExecutor` は、関数を別の isolate で実行し、その結果を `Future` として返します。isolate はプールから取られます。プールは、タスクが来ると isolate を起動し、アイドルになると停止します。Spring Boot では Bean `isolateTaskExecutor` です。

## 使う理由

isolate は一度に一つのことをします。ハンドラーが 20 MB の JSON を解析している間、サーバーはほかの誰にも応答しません。画面が画像をリサイズしている間、アプリはフレームを描画しません。`await` は助けになりません。`await` が isolate を解放するのは、何かを待っている間だけで、計算している間ではないためです。

そのような作業は別の isolate に置くべきです。数メガバイトの JSON の解析、ハッシュ計算、画像のリサイズ、レポートの作成などです。エグゼキューターは isolate を準備したままにするので、タスクは毎回 isolate の起動のコストを払わずに済みます。また、同時に動く数を制限します。

これは `@Async` の背後にある `TaskExecutor` ではありません。そちらは、タスクを同じ isolate の後のターンで実行するもので、計算する作業の助けにはなりません ([@Async](../events/async.md) を参照)。

## 例

```dart
import 'package:spring_boot_dart/spring_boot_dart.dart';

@Service()
class Reports {
  Reports(this.isolates);
  final IsolateTaskExecutor isolates;

  // 別の isolate が解析している間、呼び出した isolate は応答を続ける。
  Future<Summary> summarize(String csv) =>
      isolates.submitWith(_summarize, csv);

  // static: 引数だけが別の isolate にコピーされる。
  static Summary _summarize(String csv) => Summary.parse(csv);
}
```

```yaml
# lib/resources/application.yml
spring:
  task:
    execution:
      isolates:
        core-size: 2          # 未設定: プロセッサー数から 1 を引いた数
        queue-capacity: 100   # 未設定: 制限なし
        max-size: 4           # キューがいっぱいのときだけ到達する
        keep-alive: 30s
```

最初のタスクまで、isolate は起動されません。

## submit と submitWith

| メンバー | 意味 |
|---|---|
| `Future<R> submitWith<M, R>(task, message)` | プールの isolate で `task(message)` を実行する。トップレベル関数または static 関数向け: `message` だけがコピーされる |
| `Future<R> submit<R>(task)` | クロージャーを実行する。クロージャーが周りから使うものはすべて、一緒にコピーされる |
| `poolSize` | 今動いている isolate の数 |
| `activeCount` | 今実行中のタスクの数 |
| `queueSize` | isolate を待っているタスクの数 |
| `Future<void> shutdown()` | プールを終了する。コンテキストが閉じるときに呼び出す |

タスクは値または `Future` を返せます。isolate は一度に一つのタスクを実行します。タスクが await している間も同じです。タスクにはタイムアウトがなく、キャンセルもできません。終わらないタスクは、その isolate を占有し続けます。

## isolate を越えるもの

isolate は、ほかの isolate とメモリーを共有しません。関数、その引数、その結果はコピーされます。

- **`submitWith` を優先します。** トップレベル関数または static 関数を使い、データを引数として渡します。そうすれば、何がコピーされるかがわかります: 引数です。
- **クロージャーは、使うものをコピーします。** `submit(() => parse(text))` は `text` をコピーします。フィールドを読むクロージャーは、そのフィールドが属するオブジェクト全体と、そのオブジェクトから届くすべてのものをコピーします。
- **コピーできないオブジェクトがあります**: ソケット、タイマー、`ReceivePort`。そのどれかに届くクロージャーは、`ArgumentError` で呼び出しを失敗させます。プールは動き続け、次のタスクは実行されます。
- **Bean はそこに存在しません。** タスク用の isolate はアプリケーションを実行しません。コンテキストも、`@Autowired` も、構成もありません。タスクに必要なものは、引数として渡します。
- **ロギングの構成もありません。** タスクがログに出すものは、デフォルトの形式で、isolate の名前を付けて書かれます: `[task-1] [neon.reports] INFO: 1200 rows`。
- **エラーは戻ってきます。** タスクがスローしたものは、型 (`FormatException`) を保ったまま、Future のエラーになります。isolate は次のタスクに進みます。
- **コピーして戻せないエラーや結果** は、代わりに `IsolateTaskException` になります: エラーのテキストと、タスクの isolate のスタックトレースです (`message`、`remoteStackTrace`)。

```dart
// サービス全体をコピーし、ソケットを持っていれば失敗する:
isolates.submit(() => _summarize(this.lastCsv));

// 文字列を一つコピーする:
isolates.submitWith(_summarize, lastCsv);
```

## プール

タスクは、次のルールを順に通ります。

1. 空いている isolate がある: それがタスクを実行する。
2. 動いている isolate が `core-size` より少ない: そのタスクのために新しい isolate を起動する。
3. キューに空きがある (`queue-capacity`。未設定: 常に空きがある): タスクは待つ。
4. 動いている isolate が `max-size` より少ない: そのタスクのために新しい isolate を起動する。
5. それ以外の場合、タスクは `IsolateTaskRejectedException` で拒否される。

その結果:

- **`queue-capacity` がなければ、プールは `core-size` を超えて大きくなりません。** タスクは、いくつあっても待ちます。`max-size` は `queue-capacity` があるときだけ効果があります。
- **拒否は呼び出しがスローします。** Future のエラーとして渡されるのではなく、`submit` 自体がスローします。そのメッセージは、上げるべきキーを示します。

```text
IsolateTaskRejectedException: the pool has its 4 isolates busy and its queue is full (100); raise spring.task.execution.isolates.max-size or queue-capacity
```

- **アイドルの isolate は**、`keep-alive` の後に終了します。`allow-core-timeout: true` (デフォルト) では、最初の `core-size` 個の isolate も終了するため、何も submit しないアプリケーションにはタスク用の isolate がありません。次のタスクが、数ミリ秒でまた一つ起動します。
- **自分で終了した isolate** (kill された、またはタスクの外でのエラー) は、そのタスクを `IsolateTaskException` (`the isolate task-1 ended: ...`) で失敗させ、警告 `Isolate task-1 failed` としてログに出されます。キューは新しい isolate で進みます。
- **シャットダウン時には**、待っているタスクと実行中のタスクは `IsolateTaskRejectedException` (`the executor was shut down`) で失敗し、isolate は停止し、その後の `submit` は同じ例外をスローします。

プールは、ロガー `spring_core_dart.isolate.task` に `debug` レベルでログを出します。

```text
Starting isolate task-1: a task found no free isolate (1 of 4)
Starting isolate task-3: the queue is full (100) (3 of 4)
Isolate task-1 idle for 0:00:30.000000: stopped (2 left)
```

## ブラウザーでは

ブラウザーには、起動できる isolate がありません。それでもエグゼキューターは同じ API で存在します。タスクは呼び出した isolate で、そのイベントループの後のターンに実行されます。

- `submit` を呼び出すコードは、すべてのプラットフォームでコンパイルでき、動きます。そしてブラウザービルドには isolate のコードが入りません。
- **長いタスクは、やはりページをブロックします。** 後で始まるだけで、別の場所に移されるわけではありません。
- 何もコピーされないので、クロージャーは何でも使えます。ブラウザーで動くコードが、クロージャーがコピーされるスマートフォンでは失敗することがあります。isolate が本物である環境でテストしてください。
- `poolSize` と `queueSize` は `0` で、プールのルールは適用されません。`shutdown` の後を除いて、何も拒否されません。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.task.execution.isolates.core-size` | `int` | 未設定: マシンのプロセッサー数より一つ少ない数、最低一つ | タスクがキューで待つ前に起動される isolate の数 |
| `spring.task.execution.isolates.max-size` | `int` | 未設定: `core-size` と同じ数 | isolate の最大数。キューがいっぱいのときだけ到達する |
| `spring.task.execution.isolates.queue-capacity` | `int` | 未設定: いくつでも | isolate を待てるタスクの数 |
| `spring.task.execution.isolates.keep-alive` | `Duration` | `60s` | アイドルの isolate が停止されるまで残る時間 |
| `spring.task.execution.isolates.allow-core-timeout` | `bool` | `true` | 最初の `core-size` 個の isolate も、アイドルのときに停止するかどうか |
| `spring.task.execution.isolates.name-prefix` | `String` | `task-` | ログでの isolate の名前。番号が付く: `task-1` |

Spring Boot なしでは、`IsolateTaskExecutor(settings: IsolateTaskExecutorSettings(coreSize: 2, queueCapacity: 100, maxSize: 4))` が同じ値を受け取ります。`shutdown()` は自分で呼び出します。

## サーバーの isolate のプールがある場合

[Web サーバーのプール](../../spring-boot-starter-web/server/isolates.md) の各 isolate はアプリケーション全体を実行するため、それぞれが独自のエグゼキューターを、独自の `core-size` で持ちます。その isolate は、自分のサーバー isolate の名前を持ちます: `isolate-2-task-1`。`server.isolates.count: 4` と `core-size: 2` では、マシン上で最大 12 個の isolate が同時に計算します。リクエストを処理する 4 個と、タスクを実行する 8 個です。

## タスクマネージャーでの表示

プールの各 isolate は、[タスクマネージャー](load.md) の一つの行で、種類は `task` です。`busy` は直近の 1 秒以上の間にタスクに使った時間の割合、`active` はタスクを実行している間 `1` です。詳細には `tasks` (完了したタスクの数) と、最初の行には `queued` (待っているタスクの数) があります。

## Spring (Java) との対応

```java
Future<Summary> summary = taskExecutor.submit(() -> Summary.parse(csv));
```

```properties
spring.task.execution.pool.core-size=2
spring.task.execution.pool.max-size=4
spring.task.execution.pool.queue-capacity=100
spring.task.execution.pool.keep-alive=30s
```

`IsolateTaskExecutor` は、`spring.task.execution.pool.*` のプールを使う `ThreadPoolTaskExecutor.submit(callable)` で、`IsolateTaskRejectedException` は `TaskRejectedException` です。違いは、ここではどこでも重要になる一点です: スレッドはヒープを共有し、isolate は共有しません。Java のタスクは周りの Bean を読みます。ここでのタスクは、渡されたもののコピーを受け取り、それ以外は何も受け取りません。

## 関連項目

- [isolate](index.md)
- [isolate の負荷](load.md)
- [最初の isolate に問い合わせる](primary-isolate.md)
- [組み込みの Bean](../../spring-boot-dart/built-in-beans.md#isolate)
- [Web サーバーの isolate のプール](../../spring-boot-starter-web/server/isolates.md)
- [Durations](../conversion/durations.md)
