
# TaskScheduler

`@Scheduled` は、コードを書く時点で分かっている処理をカバーします。スケジュールが実行時に決まる場合 (ユーザーが選んだ時刻のリマインダー、画面が開いている間のポーリング、ユーザーが入力した cron) は、`TaskScheduler` の Bean を注入して、コードで処理をスケジュールします。各呼び出しは、調べたりキャンセルしたりできる `ScheduledTask` を返します。

## 使う理由

手で開始したタイマーは、保持し、キャンセルし、エラーから守らなければなりません。スケジューラーはこれを `@Scheduled` と同じ方法で行います。エラーはスケジュールを止めずにログに出され、タスクはコンテキストが閉じるときにキャンセルされ、固定レートのタスクは長い実行の後に追いつきます。

## 例

```dart
@Service()
class Reminders {
  Reminders(this.scheduler);

  final TaskScheduler scheduler;

  // ユーザーがアプリで選んだ時刻に。
  ScheduledTask remindAt(DateTime at, String text) =>
      scheduler.scheduleAt(() => notify(text), at, name: 'reminder');

  // 受信箱の画面が開いている間。呼び出し元がタスクをキャンセルする。
  ScheduledTask poll() => scheduler.scheduleWithFixedDelay(
        checkInbox,
        const Duration(seconds: 30),
      );

  // ユーザーが入力した cron。先にチェックする。
  ScheduledTask custom(String expression) => scheduler.schedule(
        exportReport,
        CronTrigger(CronExpression.parse(expression)),
      );
}

final task = reminders.poll();
final due = task.nextExecution; // 次の実行の予定時刻
task.cancel();                  // 画面が閉じた
```

## メソッド

| メソッド | タスクの実行 |
|---|---|
| `scheduleAt(task, time, name:)` | `time` に一度だけ。過ぎていればすぐに。 |
| `scheduleAtFixedRate(task, period, initialDelay:, name:)` | `period` ごと。開始の間隔で測る。プロセスの一時停止の後は、逃したすべての実行をすぐに。 |
| `scheduleWithFixedDelay(task, delay, initialDelay:, name:)` | 各実行が終わってから `delay` 後に、何度も。 |
| `schedule(task, trigger, name:)` | `Trigger` が与える時刻に。 |

タスクは `Future` を返してもよい関数です。それが完了したときに実行が終わったとみなされます。

## ScheduledTask

| メンバー | 意味 |
|---|---|
| `name` | ログでのタスクの名前。 |
| `trigger` | そのトリガー。 |
| `nextExecution` | 次の実行の予定時刻、または `null`。 |
| `runs` | これまでの実行回数。 |
| `isCancelled` | キャンセルされたかどうか。 |
| `cancel()` | それ以上の実行は始まらない。実行中のものは終わる。 |

## トリガー

| トリガー | 与えるもの |
|---|---|
| `PeriodicTrigger(period, fixedRate:, initialDelay:)` | `period` ごと。`fixedRate: true` なら開始の間隔で、そうでなければ実行の終わりから。`scheduleAtFixedRate` や `scheduleWithFixedDelay` と同じく、タスク自身のタイムラインで実行する。 |
| `CronTrigger(expression, utc:)` | `CronExpression` の時刻。ローカル時刻または UTC で。 |
| `OneShotTrigger` | 一つの時刻。 |
| 独自のもの | `nextExecution(context)`: 次の時刻、またはタスクを終えるなら `null`。 |

他のものでは表せないスケジュールのための、独自のトリガー:

```dart
// 最初は素早くポーリングし、その後 10 分ごとまで間隔を伸ばす。
final class BackOff implements Trigger {
  var _delay = const Duration(seconds: 5);

  @override
  DateTime? nextExecution(TriggerContext context) {
    final next = (context.lastCompletion ?? context.now).add(_delay);
    if (_delay < const Duration(minutes: 10)) {
      _delay *= 2;
    }
    return next;
  }
}

scheduler.schedule(checkInbox, BackOff());
```

`TriggerContext` は `now`、`lastScheduledExecution`、`lastActualExecution`、`lastCompletion` を持ちます。

## Flutter アプリで

`TaskScheduler` で開始したタスクは、バックグラウンドでもスケジュールを保ちます (そこで一時停止するのは `@Scheduled` タスクだけです)。アプリが戻ったときに追いつこうとしないよう、その画面がなくなるときにキャンセルするか、固定遅延を与えてください。

```dart
// 画面上のカウントダウン: バックグラウンドから戻ると一度だけティックする。
final tick = scheduler.scheduleWithFixedDelay(refreshCountdown, const Duration(seconds: 1));
```

## スケジューラーの Bean

スターターのスケジューラーは `TimerTaskScheduler` です。それを置き換えるには、独自の `TaskScheduler` の Bean を宣言してください。

`TaskScheduler` の Bean が複数ある場合、`@Scheduled` メソッドは、`scheduler:` で別のものを指定しない限り、プライマリーのもの、または `taskScheduler` という名前のもので実行されます。どちらもなければ起動が失敗します。Spring ならローカルのシングルスレッドのスケジューラーにフォールバックします。

`TimerTaskScheduler(now:, createTimer:, awaitTermination:, awaitTerminationPeriod:, errorHandler:)` は、テストのために時計とタイマーのファクトリーを受け取ります ([テストと時間](testing.md) を参照)。`runningTasks` は実行中のものを列挙します。独自のスケジューラーは、`Future` を返す `destroy()` (`DisposableBean`) を通して、シャットダウン時に待つことができます。

## Spring (Java) との対応

```java
ScheduledFuture<?> task = scheduler.schedule(() -> notify(text), Instant.parse(at));
```

`schedule(task, Instant)` はここでは `scheduleAt(task, DateTime)` で (Dart にはオーバーロードがありません)、`ScheduledTask` が `ScheduledFuture` の代わりになります。`PeriodicTrigger` はタスクのタイムラインで実行されます。Spring は実時間の時計でそれを計画します。`SchedulingConfigurer` と `ScheduledTaskRegistrar` はまだありません。

## 関連項目

- [@Scheduled](scheduled.md)
- [cron 式](cron.md)
- [テストと時間](testing.md)
