
# The task manager

The task manager lists what runs in the app and how busy each is: the app's own isolate, the engine's threads that draw and decode for it, and every isolate the app starts for heavy work. A small table over the app shows the essentials; the debug panel has every number.

## Why

"The app stutters" has four different causes in a Flutter app, and each has its own fix:

- the Dart code is busy (the `main` row is late): move the work to an isolate, with the [task executor](../spring-core-dart/isolates/task-executor.md);
- drawing takes too long (the `raster` row is busy): fewer layers, smaller pictures, cached pictures;
- the platform answers late (the `platform` row): a plugin does too much on the platform's thread;
- pictures decode slowly (the `io` row): too many or too large at once.

Flutter's DevTools shows this on a developer's machine. The task manager shows it in the running app, on any device and in a release build, where there is no VM service to ask.

## Example

```yaml
spring:
  flutter:
    debug:
      isolates:
        enabled: true          # in every build; not set: debug and profile only
        position: bottom-right
```

Run the app and press ⌘⇧I (Ctrl+Shift+I), or on a phone tap seven times quickly and hold the eighth. The table shows in its corner, a line per row: the name, how busy, how late.

```
main      ▂  3%   0.4 ms
raster    ▅ 31%
platform         1.2 ms
io               0.8 ms
task-1    █ 96%
```

## The rows

| Row | What it is | What is measured |
|---|---|---|
| `main` | The app's isolate: your Dart code and Flutter's build and layout. The engine's UI thread | How late its event loop runs (`lag`) and from that how busy it is; the frames' build times (average and worst); the memory of the process |
| `raster` | The engine's thread that draws the frames | The share of the time spent drawing (`busy`), the frames' raster times, the sizes of the layer and picture caches |
| `platform` | The platform's main thread: plugins, the keyboard, the system's views | The round trip of a harmless call of an engine channel, every two seconds |
| `io` | The engine's threads that decode pictures | The round trip of decoding a picture of one pixel, every two seconds |
| `task-1`, … | The isolates of the [task executor](../spring-core-dart/isolates/task-executor.md), while they exist | The share of the time spent in tasks, the tasks done, those waiting |
| a name of yours | An isolate the app starts itself, shown with `IsolateLoads.track` | That it runs |

A row has only the numbers its source can measure. `main` is one row from two sources: the framework's sampler gives the lag, the engine's frame times are added to it.

**In a browser** there are no platform and IO threads: the rows are `main` and `raster`. The memory is the JavaScript heap, where the browser tells it (Chromium).

**Where the engine runs Dart on the platform's thread** (the macOS desktop embedder does by default), `platform` waits as long as `main` does: they are one thread there.

An isolate the app starts with `Isolate.run` or `compute` is not found by itself: a compiled app cannot list its isolates. Start the work through the task executor, or show it with one call:

```dart
final report = await isolateLoads.track('report', Isolate.run(buildReport));
```

## It measures only while you look

Nothing is measured while the table is hidden and the panel's tab is closed. The first look starts the timers (the first second has no numbers yet); half a minute after the last look they stop by themselves. So a release build with the feature in it pays for it only when someone opens it.

The table reads every `interval` (a second). The lag of `main` is how late a timer due every 100 ms fires: work that ends between two timers does not show, so a `busy` of 3 % says the isolate keeps up, not that it used 3 % of a processor.

## The debug panel

The [debug panel](debug-panel.md) has an **Isolates** tab with the full table: every row with its kind, busy share, lag, longest lag, what it is working on, memory and details (the frame times, the cache sizes, the tasks done). **Copy JSON** puts the rows on the clipboard, for a bug report.

The table lives in the [dock of the debug overlays](overlays.md) with the frame meter and the timeline: in one corner they stack on a laptop and become pages to swipe on a phone.

## In the build or not

Like the other debug features, the task manager is a module of its own, decided by `spring.flutter.debug.isolates.enabled`:

| Value | The app |
|---|---|
| `true` | Has it in every build, a release too |
| `false` | Has no code of it |
| not set | Has it in debug and profile builds; a release compiles it away |

Without it the app has no code that measures the engine's threads. The `isolateLoads` bean is still there, with the rows that cost nothing to have (`main`, the task executor's isolates): a screen of your own can read it.

## A row of your own

A bean that implements `IsolateLoadSource` adds rows: the task manager asks every source.

```dart
@Component()
class SyncLoad implements IsolateLoadSource {
  SyncLoad(this.sync);
  final SyncService sync;

  @override
  List<IsolateLoad> loads() => [
    IsolateLoad(
      name: 'sync',
      kind: 'own',
      active: sync.pending,
      details: {'uploaded': sync.uploaded},
    ),
  ];
}
```

See [Isolates and their load](../spring-core-dart/isolates/load.md).

## The properties

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.debug.isolates.enabled` | bool | not set | Whether the build has the task manager (see above) |
| `spring.flutter.debug.isolates.position` | corner | `bottom-right` | The corner of its table |
| `spring.flutter.debug.isolates.interval` | duration | `1s` | How often the table and the tab read the rows |

The action is `debug.isolates`; change its keys with `spring.flutter.shortcuts.debug.isolates` (see [Keyboard shortcuts and taps](shortcuts.md)). On the web Ctrl+Shift+I is also the browser's own shortcut for its developer tools on Windows and Linux: give the action other keys there, or use the taps.

## See also

- [Isolates and their load](../spring-core-dart/isolates/load.md)
- [The task executor](../spring-core-dart/isolates/task-executor.md)
- [Debug overlays](overlays.md)
- [The frame meter](frame-meter.md)
- [The timeline](timeline.md)
