Skip to content

[embedder] Add FlutterEngineSpawn API for engine group spawning - #50

Draft
xiaowei-guan wants to merge 9 commits into
flutter-tizen:flutter-3.47.5from
xiaowei-guan:flutter-3.47.5-engine-group
Draft

xiaowei-guan wants to merge 9 commits into
flutter-tizen:flutter-3.47.5from
xiaowei-guan:flutter-3.47.5-engine-group

Conversation

@xiaowei-guan

Copy link
Copy Markdown

Why spawn engines?

Android and iOS already have engine groups (FlutterEngineGroup): additional
engines spawned from a running one share its Dart VM, isolate snapshot, and
isolate group heap — far cheaper than independent engines. The C embedder API
has no equivalent, so embedders needing multiple Flutter UIs in one process
must pay full VM + snapshot + thread cost per engine — impractical on
memory-constrained devices like Smart TVs, and too slow for instantly-appearing
UIs.

The shell already implements spawning internally (Shell::Spawn); it is just
not exposed. This PR adds FlutterEngineSpawn to embedder.h:

  • Less memory — spawns share the parent's VM, snapshot, and isolate group heap.
  • Faster startup — no VM init, no snapshot load, no new threads; the spawn
    is returned already running its Dart entrypoint.
  • Cheap Dart cooperation — isolates in one group exchange messages without
    cross-group overhead.

Use cases

  • Multi-view UIs on one device (primary target): TV home screens with
    several live surfaces — app cards, previews, PiP — each with its own Flutter
    UI tree, all sharing one VM. Tizen TV multi-view support is built on this
    API (follow-ups: TizenEngineGroup + per-view pixel-buffer render targets).
  • Instant auxiliary UIs: overlays, settings panes, on-screen keyboards,
    splash screens that must appear immediately.
  • Independent mini-apps from one kernel snapshot: dashboards/app grids
    where each cell runs a separate dart_entrypoint with its own route/args.
  • Companion worker engines in the same isolate group for cheap UI↔worker
    data exchange.

@xiaowei-guan
xiaowei-guan marked this pull request as draft November 12, 2026 01:23
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-20T08:20:25.828390Z 4e636db Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 38a56d19fc

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@xiaowei-guan
xiaowei-guan force-pushed the flutter-3.47.5-engine-group branch from 38a56d1 to 96eedc4 Compare November 16, 2026 10:35
Add a new embedder API that spawns a running child engine in the same isolate group as a running parent engine. The spawned engine shares the parent's threads, Dart VM, isolate snapshot and isolate group heap, making it significantly cheaper to create than an independent engine.

- Add FlutterSpawnConfig and FlutterEngineSpawn (also exposed through FlutterEngineProcTable) to the public embedder API. - FlutterEngineSpawn rebuilds the platform dispatch table, platform view creation callback and external texture resolver from the parent's captured FlutterProjectArgs/FlutterRendererConfig, handing every callback the spawn's own user data baton, and runs the child with RunConfiguration::InferFromSettings(..., kExistingGroup). - Extract BuildPlatformDispatchTable, InferExternalViewEmbedderFromArgs and the spawn-source plumbing out of FlutterEngineInitialize so both entry points share the same construction logic. - EmbedderEngine keeps a sanitized copy of the init-time args for spawning and refuses to spawn from an engine that has not run.

Unit tests cover default spawning, custom entrypoints with @pragma('vm:entry-point'), entrypoint arguments and initial route passthrough, per-spawn user data routing, lifecycle contracts and argument error paths.
@xiaowei-guan

Copy link
Copy Markdown
Author

@chatgpt-codex-connector code review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1eebd0d189

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Address issues found in the review of FlutterEngineSpawn and fix its
documentation to match the actual behavior:

- Share the parent engine's ThreadHost with spawned engines via
  std::shared_ptr (with a null guard) instead of handing out a raw
  pointer into parent-owned storage.
- Call NotifyCreated() in EmbedderEngine::Spawn so the spawned engine
  actually gets a rendering surface; without it the spawned engine
  could never render.
- Leave engine_out untouched on failure by removing the premature
  *engine_out = nullptr assignment, as documented and as every other
  embedder API already behaves.
- Validate that no element of spawn_config.dart_entrypoint_args is
  null and reject such configs with kInvalidArguments.
- Correct the API docs: root isolate startup is queued on the shared
  UI task runner and runs asynchronously after the call returns; the
  settings-level root_isolate_create_callback and log_message_callback
  are inherited with the parent engine's user data; the compositor is
  inherited with its own baton (rebind via SetCompositor); clarify
  null spawn config semantics.

Tests:
- SpawnedEngineCanRender and lifecycle/error-path coverage for the
  above; SpawnErrorPaths now also asserts engine_out is unchanged on
  failure via a sentinel.
@xiaowei-guan
xiaowei-guan force-pushed the flutter-3.47.5-engine-group branch from 1eebd0d to e69f4cc Compare November 16, 2026 12:41
@xiaowei-guan

Copy link
Copy Markdown
Author

@chatgpt-codex-connector code review.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e69f4cc438

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Move the FlutterEngineSpawn declaration inside the existing prototype
guard so clients defining FLUTTER_ENGINE_NO_PROTOTYPES cannot call it
directly. Keep FlutterSpawnConfig, FlutterEngineSpawnFnPtr, and the
proc-table Spawn member available for dynamic-loading embedders.
Own the Vulkan instance and device extension names, their pointer arrays,
and the pipeline cache path in EmbedderEngine. Spawned engines may use
these values after the embedder is allowed to release the original inputs.

Respect struct_size when reading cache_path and add a regression test that
verifies retained data remains valid after the source strings and arrays
are destroyed.
Document that root isolate startup and callbacks may occur before
FlutterEngineSpawn returns and before engine_out is populated.
Flush all engines sharing a custom UI task runner, preserve shared runners during child shutdown, and handle shell creation and argument validation failures. Add spawn regression coverage.
@xiaowei-guan

Copy link
Copy Markdown
Author

@chatgpt-codex-connector code review.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4e636db2af

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Copy only fields advertised by the active renderer sub-struct when
retaining spawn sources. Avoid reading past shorter configurations
provided by older embedders during engine initialization while
preserving Vulkan extension and cache path deep copies.

Add regression coverage for truncated OpenGL renderer configs.
Remove the null-result guard from Shell::Spawn and its regression test.

Co-Authored-By: Cline SR
@xiaowei-guan

Copy link
Copy Markdown
Author

@chatgpt-codex-connector code review.

@chatgpt-codex-connector

Copy link
Copy Markdown

To use Codex here, create a Codex account and connect to github.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant