
# @Scheduled

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

## 使う理由

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

## 例

```dart
@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.md) を参照)。`-` はタスクを無効にする。 | `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` に置き、プロファイルごとに変えられます。

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

```properties
# 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 のプール](../spring-boot-starter-web/server/isolates.md) を動かすとき (`server.isolates.count`)、すべての isolate がアプリケーション全体を実行するため、すべての isolate が `@Scheduled` メソッドを持つ Bean を持ちます。デフォルトでは、アプリケーションの最初の isolate だけがそれらをスケジュールします。ジョブは isolate ごとに一度ではなく、アプリケーションで一度だけ実行されます。

```properties
# 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) との対応

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

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

## 関連項目

- [cron 式](cron.md)
- [TaskScheduler](task-scheduler.md)
- [isolate のプール](../spring-boot-starter-web/server/isolates.md)
- [すべてのプロパティ](properties.md)
