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
mainrow is late): move the work to an isolate, with the task executor; - drawing takes too long (the
rasterrow is busy): fewer layers, smaller pictures, cached pictures; - the platform answers late (the
platformrow): a plugin does too much on the platform's thread; - pictures decode slowly (the
iorow): 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
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, 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:
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 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 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.
@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},
),
];
}
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). 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.