@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。
ルール
- メソッドは public で、パラメーターを取ってはいけません。
Futureを返してもかまいません。その Future が完了したときに実行が終わったとみなされます。 - 一つのメソッドに複数の
@Scheduledを付けると、複数のスケジュールになります。 - スケジュールされるのはシングルトンの Bean だけです。
@Scope('prototype')のような別のスコープの Bean の@Scheduledは、警告とともに無視されます。 - 誤った属性は
Class.methodを示すメッセージとともに起動を止めます。2 つの種類を同時に、どれもない、不正なまたは空白の cron、不明な zone やscheduler、ないプロパティ、負の期間、ゼロのfixedRateやfixedDelayです。 - メソッドは、他の Bean から見えるとおりの Bean で呼ばれるため、AOP のアドバイス (
@Around、@Cacheable...) が適用されます。
プロパティからのスケジュール
テキストの属性と 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 回実行されることは決してありません。
fixedDelay: 間隔は、実行が (そのFutureを含めて) 完了したときに始まります。fixedRate: 各実行は、前の実行の予定時刻から一周期後が予定時刻です。実行が周期より長くかかる (あるいは、他の処理で忙しい Isolate のせいで遅れて始まる) と、その間に予定時刻になった実行は、Spring のスケジューラーと同じく、その直後に一つずつ始まり、レートに追いつくまで続きます。最初の実行に 1 秒かかる 300 ms のレートは、0 ms、続いて 1000、1000、1000 ms、その後 1200、1500... に始まります。cron: 次の時刻は実行の後に計算されるため、長い実行の間に逃した時刻はスキップされます。
プロセスの一時停止の後の固定レート
固定レートのタスクは、長い実行の後だけでなく、どんな一時停止の後にも追いつこうとします。停止したプロセス、バックグラウンドで一時停止したアプリ、制限されたブラウザーのタブが再び動くと、その間に予定時刻になったすべての実行がすぐに、一つずつ始まります。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 が自分のために行わなければならないもの: メモリーに持つものの更新 |
- この設定は、アプリケーションのすべての
@Scheduledメソッドに対するものです。一つのジョブをすべての isolate で実行し、他のジョブを一度だけ実行するには、allを設定し、一度だけ実行しなければならないジョブの Bean に@ConditionalOnPrimaryIsolate()を付けます。 primaryでも、他の isolate に Bean は存在します。そのスケジュールだけが省かれます。スターターはdebugで@Scheduled methods of Maintenance run in the primary isolate only (spring.task.scheduling.isolates=primary)とログに出します。@Scheduledメソッドが更新するキャッシュは、primaryでは最初の isolate でだけ更新されます。他の isolate は古い値を持ち続けます。これがallを使う場面です。- プールがなければ、この設定は何も変えません。
シャットダウン
コンテキストを閉じると、すべてのタスクがキャンセルされます。それ以上の実行は始まりません。実行中のものが中断されることは決してありません。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 はまだスケジュールされません。