@Scheduled

Bean のメソッドに @Scheduled を付けると、アプリケーションが自分でそれを実行します。一定の周期ごと (fixedRate)、各実行の後に間隔を置いて (fixedDelay)、cron の時刻に (cron)、あるいは遅延の後に一度だけ (initialDelay だけ) です。メソッドはパラメーターを取らず、Future を返してもかまいません。

使う理由

繰り返しの処理は、起動時にどこかで開始した Timer ではなく、それを行うメソッドに、スケジュールを隣に書いて置くべきです。スターターは、忘れやすいことも扱います。スケジュールを止めてはならないエラー、シャットダウン時のキャンセル、周期より長くかかる実行です。

例

@Component()
class Maintenance {
  // 5 分ごとに実行が始まる。開始の間隔で測る。
  @Scheduled(fixedRate: Duration(minutes: 5))
  void refreshCache() => cache.refresh();

  // 各同期が (Future を含めて) 完了してから 30 秒後。
  @Scheduled(fixedDelay: Duration(seconds: 30), initialDelay: Duration(seconds: 10))
  Future<void> sync() => server.sync();

  // 毎晩 3:00、UTC。
  @Scheduled(cron: '0 0 3 * * *', zone: 'UTC')
  Future<void> cleanup() => files.deleteOld();

  // 起動の 1 分後に一度だけ (Spring 6.1)。
  @Scheduled(initialDelay: Duration(minutes: 1))
  void warmUp() => cache.warmUp();

  // 設定から。プロファイルが cron を設定しない限り無効。
  @Scheduled(cron: r'${reports.cleanup-cron:-}')
  void reportCleanup() => reports.cleanup();

  // 一つのメソッドに 2 つのスケジュール。
  @Scheduled(cron: '0 0 9 * * MON-FRI')
  @Scheduled(cron: '0 0 11 * * SAT')
  void digest() => mail.sendDigest();
}

属性

cron、fixedRate、fixedDelay (またはその *String の形) のうち、ちょうど一つを指定します。そのどれもなしに initialDelay だけを指定すると、メソッドを一度だけ実行します。

属性 意味 例
fixedRate 周期ごとに実行を開始する。開始の間隔で測る。長い実行やプロセスの一時停止の間に逃した実行は、続けざまに始まる。 fixedRate: Duration(minutes: 5)
fixedDelay 各実行が完了してからこれだけ待つ。ポーリングや UI のティック向け。 fixedDelay: Duration(seconds: 30)
initialDelay 最初の実行の前に待つ (cron とは併用しない)。単独では、その後に一度だけ実行する。 initialDelay: Duration(seconds: 10)
cron cron の時刻に実行する (cron 式 を参照)。- はタスクを無効にする。 cron: '0 */15 * * * *'
zone cron のタイムゾーン: ローカル時刻なら省略、または 'UTC' ('Z'、'GMT' も)。 zone: 'UTC'
scheduler 複数あるときに実行に使う TaskScheduler の Bean。修飾子または Bean 名で (${...} も可)。デフォルト: 唯一のもの、プライマリーのもの、または taskScheduler。 scheduler: 'reportsScheduler'
fixedRateString、fixedDelayString、initialDelayString 同じものをテキストで。${...} のプレースホルダーと Spring Boot の期間を使える。空白の値は、解決後も、設定されていないとみなされる。 fixedRateString: r'${reports.rate:5m}'

テキストの形での期間: 500 (ミリ秒)、10s、5m、2h、1d、PT1H30M。

ルール

プロパティからのスケジュール

テキストの属性と cron は ${...} のプレースホルダーを解決するため、スケジュールを application.properties に置き、プロファイルごとに変えられます。

# lib/resources/application.properties
reports.rate=10m
reports.cleanup-cron=0 0 3 * * *
# lib/resources/application-test.properties
reports.cleanup-cron=-

長い実行と重なり

すべては Dart のイベントループで実行されるため、タスクが同時に 2 回実行されることは決してありません。

プロセスの一時停止の後の固定レート

固定レートのタスクは、長い実行の後だけでなく、どんな一時停止の後にも追いつこうとします。停止したプロセス、バックグラウンドで一時停止したアプリ、制限されたブラウザーのタブが再び動くと、その間に予定時刻になったすべての実行がすぐに、一つずつ始まります。5 秒停止した後の 100 ms のレートは、同じミリ秒の中で約 50 回実行されます。Spring の ThreadPoolTaskScheduler も同じことをします。一時停止は、システムの単調時計がそれを数える範囲で数えられます。デバイスがスリープしていた時間は、たいてい数えられません。fixedDelay のタスクは一時停止の後に一度だけ実行して遅延を保ち、cron も一度だけ実行します。

これは、周期ごとに一度行わなければならない処理に向いています。最新の実行だけが重要なポーリングや UI のティックには、fixedDelay を使ってください。

Flutter アプリでは、スターターはアプリがバックグラウンドにある間 @Scheduled タスクを止め、戻ったときに新たにスケジュールするため、追いつこうとはしません (spring.flutter.lifecycle.pause-in-background=false でない限り)。

isolate のプールがある場合

Web サーバーが isolate のプール を動かすとき (server.isolates.count)、すべての isolate がアプリケーション全体を実行するため、すべての isolate が @Scheduled メソッドを持つ Bean を持ちます。デフォルトでは、アプリケーションの最初の isolate だけがそれらをスケジュールします。ジョブは isolate ごとに一度ではなく、アプリケーションで一度だけ実行されます。

# primary (デフォルト): 最初の isolate だけ。all: すべての isolate。
spring.task.scheduling.isolates=all
spring.task.scheduling.isolates @Scheduled メソッドが実行される場所 用途
primary (デフォルト) アプリケーションの最初の isolate である main 夜間のレポート、クリーンアップ、キューのポーリング: 一度だけ行わなければならないもの
all すべての isolate。それぞれ自分のタイマーで 各 isolate が自分のために行わなければならないもの: メモリーに持つものの更新

シャットダウン

コンテキストを閉じると、すべてのタスクがキャンセルされます。それ以上の実行は始まりません。実行中のものが中断されることは決してありません。spring.task.scheduling.shutdown.await-termination=true では、コンテキストの closeAsync() は実行中のものを (最大 await-termination-period だけ) 待ちます。同期的な close() は待てません。

Spring (Java) との対応

@Scheduled(fixedDelay = 30, initialDelay = 10, timeUnit = TimeUnit.SECONDS)
void sync() { server.sync(); }

属性は Spring のもので、数値と timeUnit の代わりに Duration を使います。返された Future は fixedRate と cron でも待たれるため、遅い実行は次の実行と重なるのではなく、それを遅らせます。Spring は返された CompletableFuture を待ちません。プロトタイプの Bean はまだスケジュールされません。

関連項目