TaskScheduler

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

使う理由

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

例

@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。

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

// 最初は素早くポーリングし、その後 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 タスクだけです)。アプリが戻ったときに追いつこうとしないよう、その画面がなくなるときにキャンセルするか、固定遅延を与えてください。

// 画面上のカウントダウン: バックグラウンドから戻ると一度だけティックする。
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:) は、テストのために時計とタイマーのファクトリーを受け取ります (テストと時間 を参照)。runningTasks は実行中のものを列挙します。独自のスケジューラーは、Future を返す destroy() (DisposableBean) を通して、シャットダウン時に待つことができます。

Spring (Java) との対応

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

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

関連項目