
# TaskScheduler

`@Scheduled` covers work known when the code is written. When the schedule is decided at runtime (a reminder at a time the user picked, a poll that runs while a screen is open, a cron a user typed), inject the `TaskScheduler` bean and schedule the work in code. Each call returns a `ScheduledTask` you can inspect and cancel.

## Why

Timers started by hand must be kept, cancelled and guarded against errors. The scheduler does this the same way as for `@Scheduled`: errors are logged without stopping the schedule, tasks are cancelled when the context closes, and fixed-rate tasks catch up after a long run.

## Example

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

  final TaskScheduler scheduler;

  // At the time the user picked in the app.
  ScheduledTask remindAt(DateTime at, String text) =>
      scheduler.scheduleAt(() => notify(text), at, name: 'reminder');

  // While the inbox screen is open; the caller cancels the task.
  ScheduledTask poll() => scheduler.scheduleWithFixedDelay(
        checkInbox,
        const Duration(seconds: 30),
      );

  // A cron the user typed, checked first.
  ScheduledTask custom(String expression) => scheduler.schedule(
        exportReport,
        CronTrigger(CronExpression.parse(expression)),
      );
}

final task = reminders.poll();
final due = task.nextExecution; // when the next run is due
task.cancel();                  // the screen closed
```

## Methods

| Method | Runs the task |
|---|---|
| `scheduleAt(task, time, name:)` | Once at `time`, or right away when it has passed. |
| `scheduleAtFixedRate(task, period, initialDelay:, name:)` | Every `period`, measured between starts; after a pause of the process, every missed run at once. |
| `scheduleWithFixedDelay(task, delay, initialDelay:, name:)` | Again and again, `delay` after each run has finished. |
| `schedule(task, trigger, name:)` | At the times a `Trigger` gives. |

A task is a function that may return a `Future`; the run counts as finished when it completes.

## ScheduledTask

| Member | Meaning |
|---|---|
| `name` | The task's name, in logs. |
| `trigger` | Its trigger. |
| `nextExecution` | When the next run is due, or `null`. |
| `runs` | The number of runs so far. |
| `isCancelled` | Whether it was cancelled. |
| `cancel()` | No further run starts; a run going on finishes. |

## Triggers

| Trigger | Gives |
|---|---|
| `PeriodicTrigger(period, fixedRate:, initialDelay:)` | Every `period`, between starts with `fixedRate: true`, else from the end of a run. Runs as `scheduleAtFixedRate` or `scheduleWithFixedDelay` do, on the task's own timeline. |
| `CronTrigger(expression, utc:)` | The times of a `CronExpression`, in local time or UTC. |
| `OneShotTrigger` | One time. |
| your own | `nextExecution(context)`: the next time, or `null` to end the task. |

A trigger of your own, for a schedule the others cannot express:

```dart
// Polls quickly at first, then backs off up to every 10 minutes.
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` has `now`, `lastScheduledExecution`, `lastActualExecution` and `lastCompletion`.

## In a Flutter app

Tasks started with a `TaskScheduler` keep their schedule in the background (only `@Scheduled` tasks are paused there). Cancel them when their screen goes away, or give them a fixed delay, so they do not catch up when the app comes back:

```dart
// A countdown on screen: back from the background it ticks once.
final tick = scheduler.scheduleWithFixedDelay(refreshCountdown, const Duration(seconds: 1));
```

## The scheduler bean

The starter's scheduler is a `TimerTaskScheduler`. Declare your own `TaskScheduler` bean to replace it.

With several `TaskScheduler` beans, `@Scheduled` methods run on the primary one or the one named `taskScheduler`, unless they name another with `scheduler:`. When neither exists, the start fails; Spring would fall back to a local single-threaded scheduler.

`TimerTaskScheduler(now:, createTimer:, awaitTermination:, awaitTerminationPeriod:, errorHandler:)` takes a clock and a timer factory for tests (see [Testing and time](testing.md)). `runningTasks` lists the runs going on. A scheduler of your own can wait at shutdown through a `destroy()` that returns a `Future` (`DisposableBean`).

## In Spring (Java)

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

`schedule(task, Instant)` is `scheduleAt(task, DateTime)` here (Dart has no overloads), and a `ScheduledTask` replaces `ScheduledFuture`. A `PeriodicTrigger` runs on the task's timeline; Spring plans it with the wall clock. `SchedulingConfigurer` and `ScheduledTaskRegistrar` are not here yet.

## See also

- [@Scheduled](scheduled.md)
- [Cron expressions](cron.md)
- [Testing and time](testing.md)
