Allow embedders to specify a render task runner description.

Embedders may use this to specify a thread whose event loop is managed by them
instead of the engine. In addition, specifying the same task runner for both
the platform and render task runners allows embedders to effectively perform
GPU rendering operations on the platform thread.

To affect this change, the following non breaking changes to the API have been
made:

* The `FlutterCustomTaskRunners` struct now has a new field `render_task_runner`
  for the specification of a custom render task runner.
* The `FlutterTaskRunnerDescription` has a new field `identifier`. Embedders
  must supply a unique identifier for each task runner they specify. In
  addition, when describing multiple task runners that run their tasks on the
  same thread, their identifiers must match.
* The embedder may need to process tasks during `FlutterEngineRun` and
  `FlutterEngineShutdown`. However, the embedder doesn't have the Flutter engine
  handle before `FlutterEngineRun` and is supposed to relinquish handle right
  before `FlutterEngineShutdown`. Since the embedder needs the Flutter engine
  handle to service tasks on other threads while these calls are underway,
  there exist opportunities for deadlock. To work around this scenario, three
  new calls have been added that allow more deliberate management of the Flutter
  engine instance.
  * `FlutterEngineRun` can be replaced with `FlutterEngineInitialize` and
    `FlutterEngineRunInitialized`. The embedder can obtain a handle to the
    engine after the first call but the engine will not post any tasks to custom
    task runners specified by the embedder till the
    `FlutterEngineRunInitialized` call. Embedders can guard the Flutter engine
    handle behind a mutex for safe task runner interop.
  * `FlutterEngineShutdown` can be preceded by the `FlutterEngineDeinitialize`
    call. After this call the Flutter engine will no longer post tasks onto
    embedder managed task runners. It is still embedder responsibility to
    collect the Flutter engine handle via `FlutterEngineShutdown`.
* To maintain backwards compatibility with the old APIs, `FlutterEngineRun` is
  now just a convenience for `FlutterEngineInitialize` and
  `FlutterEngineRunInitilaized`. `FlutterEngineShutdown` now implicitly calls
  `FlutterEngineDeinitialize` as well. This allows existing users who don't care
  are custom task runner interop to keep using the old APIs.
* Adds complete test coverage for both old and new paths.

Fixes flutter/flutter#42460
Prerequisite for flutter/flutter#17579

Author: chinmaygarde

shell/platform/embedder/embedder.cc

@@ -557,6 +557,22 @@ FlutterEngineResult FlutterEngineRun(size_t version,
                                      void* user_data,
                                      FLUTTER_API_SYMBOL(FlutterEngine) *
                                          engine_out) {
+  auto result =
+      FlutterEngineInitialize(version, config, args, user_data, engine_out);
+
+  if (result != kSuccess) {
+    return result;
+  }
+
+  return FlutterEngineRunInitialized(*engine_out);
+}
+
+FlutterEngineResult FlutterEngineInitialize(size_t version,
+                                            const FlutterRendererConfig* config,
+                                            const FlutterProjectArgs* args,
+                                            void* user_data,
+                                            FLUTTER_API_SYMBOL(FlutterEngine) *
+                                                engine_out) {
   // Step 0: Figure out arguments for shell creation.
   if (version != FLUTTER_ENGINE_VERSION) {
     return LOG_EMBEDDER_ERROR(kInvalidLibraryVersion);
@@ -861,26 +877,6 @@ FlutterEngineResult FlutterEngineRun(size_t version,
     return LOG_EMBEDDER_ERROR(kInvalidArguments);
   }
 
-  // Step 1: Create the engine.
-  auto embedder_engine =
-      std::make_unique<flutter::EmbedderEngine>(std::move(thread_host),    //
-                                                std::move(task_runners),   //
-                                                settings,                  //
-                                                on_create_platform_view,   //
-                                                on_create_rasterizer,      //
-                                                external_texture_callback  //
-      );
-
-  if (!embedder_engine->IsValid()) {
-    return LOG_EMBEDDER_ERROR(kInvalidArguments);
-  }
-
-  // Step 2: Setup the rendering surface.
-  if (!embedder_engine->NotifyCreated()) {
-    return LOG_EMBEDDER_ERROR(kInvalidArguments);
-  }
-
-  // Step 3: Run the engine.
   auto run_configuration =
       flutter::RunConfiguration::InferFromSettings(settings);
 
@@ -895,23 +891,77 @@ FlutterEngineResult FlutterEngineRun(size_t version,
     return LOG_EMBEDDER_ERROR(kInvalidArguments);
   }
 
-  if (!embedder_engine->Run(std::move(run_configuration))) {
-    return LOG_EMBEDDER_ERROR(kInvalidArguments);
-  }
+  // Create the engine but don't launch the shell or run the root isolate.
+  auto embedder_engine = std::make_unique<flutter::EmbedderEngine>(
+      std::move(thread_host),        //
+      std::move(task_runners),       //
+      std::move(settings),           //
+      std::move(run_configuration),  //
+      on_create_platform_view,       //
+      on_create_rasterizer,          //
+      external_texture_callback      //
+  );
 
-  // Finally! Release the ownership of the embedder engine to the caller.
+  // Release the ownership of the embedder engine to the caller.
   *engine_out = reinterpret_cast<FLUTTER_API_SYMBOL(FlutterEngine)>(
       embedder_engine.release());
   return kSuccess;
 }
 
-FlutterEngineResult FlutterEngineShutdown(FLUTTER_API_SYMBOL(FlutterEngine)
-                                              engine) {
+FlutterEngineResult FlutterEngineRunInitialized(
+    FLUTTER_API_SYMBOL(FlutterEngine) engine) {
+  if (!engine) {
+    return LOG_EMBEDDER_ERROR(kInvalidArguments);
+  }
+
+  auto embedder_engine = reinterpret_cast<flutter::EmbedderEngine*>(engine);
+
+  // The engine must not already be running. Initialize may only be called once
+  // on an engine instance.
+  if (embedder_engine->IsValid()) {
+    return LOG_EMBEDDER_ERROR(kInvalidArguments);
+  }
+
+  // Step 1: Launch the shell.
+  if (!embedder_engine->LaunchShell()) {
+    FML_LOG(ERROR) << "Could not launch the engine using supplied "
+                      "initialization arguments.";
+    return LOG_EMBEDDER_ERROR(kInvalidArguments);
+  }
+
+  // Step 2: Tell the platform view to initialize itself.
+  if (!embedder_engine->NotifyCreated()) {
+    return LOG_EMBEDDER_ERROR(kInvalidArguments);
+  }
+
+  // Step 3: Launch the root isolate.
+  if (!embedder_engine->RunRootIsolate()) {
+    return LOG_EMBEDDER_ERROR(kInvalidArguments);
+  }
+
+  return kSuccess;
+}
+
+FLUTTER_EXPORT
+FlutterEngineResult FlutterEngineDeinitialize(FLUTTER_API_SYMBOL(FlutterEngine)
+                                                  engine) {
   if (engine == nullptr) {
     return LOG_EMBEDDER_ERROR(kInvalidArguments);
   }
+
   auto embedder_engine = reinterpret_cast<flutter::EmbedderEngine*>(engine);
   embedder_engine->NotifyDestroyed();
+  embedder_engine->CollectShell();
+  return kSuccess;
+}
+
+FlutterEngineResult FlutterEngineShutdown(FLUTTER_API_SYMBOL(FlutterEngine)
+                                              engine) {
+  auto result = FlutterEngineDeinitialize(engine);
+  if (result != kSuccess) {
+    return result;
+  }
+  auto embedder_engine = reinterpret_cast<flutter::EmbedderEngine*>(engine);
   delete embedder_engine;
   return kSuccess;
 }

shell/platform/embedder/embedder.h

@@ -603,14 +603,24 @@ typedef struct {
   ///
   /// @attention     This field is required.
   FlutterTaskRunnerPostTaskCallback post_task_callback;
+  /// A unique identifier for the task runner. If multiple task runners service
+  /// tasks on the same thread, their identifiers must match.
+  size_t identifier;
 } FlutterTaskRunnerDescription;
 
 typedef struct {
   /// The size of this struct. Must be sizeof(FlutterCustomTaskRunners).
   size_t struct_size;
   /// Specify the task runner for the thread on which the `FlutterEngineRun`
-  /// call is made.
+  /// call is made. The same task runner description can be specified for both
+  /// the render and platform task runners. This makes the Flutter engine use
+  /// the same thread for both task runners.
   const FlutterTaskRunnerDescription* platform_task_runner;
+  /// Specify the task runner for the thread on which the render tasks will be
+  /// run. The same task runner description can be specified for both the render
+  /// and platform task runners. This makes the Flutter engine use the same
+  /// thread for both task runners.
+  const FlutterTaskRunnerDescription* render_task_runner;
 } FlutterCustomTaskRunners;
 
 typedef struct {
@@ -950,6 +960,32 @@ typedef struct {
   const FlutterCompositor* compositor;
 } FlutterProjectArgs;
 
+//------------------------------------------------------------------------------
+/// @brief      Initialize and run a Flutter engine instance and return a handle
+///             to it. This is a convenience method for the the pair of calls to
+///             `FlutterEngineInitialize` and `FlutterEngineRunInitialized`.
+///
+/// @note       This method of running a Flutter engine works well except in
+///             cases where the embedder specifies custom task runners via
+///             `FlutterProjectArgs::custom_task_runners`. In such cases, the
+///             engine may need the embedder to post tasks back to it before
+///             `FlutterEngineRun` has returned. Embedders can only post tasks
+///             to the engine if they have a handle to the engine. In such
+///             cases, embedders are advised to get the engine handle via the
+///             `FlutterInitializeCall`. Then they can call
+///             `FlutterEngineRunInitialized` knowing that they will be able to
+///             service custom tasks on other threads with the engine handle.
+///
+/// @param[in]  version    The Flutter embedder API version. Must be
+///                        FLUTTER_ENGINE_VERSION.
+/// @param[in]  config     The renderer configuration.
+/// @param[in]  args       The Flutter project arguments.
+/// @param      user_data  A user data baton passed back to embedders in
+///                        callbacks.
+/// @param[out] engine_out The engine handle on successful engine creation.
+///
+/// @return     The result of the call to run the Flutter engine.
+///
 FLUTTER_EXPORT
 FlutterEngineResult FlutterEngineRun(size_t version,
                                      const FlutterRendererConfig* config,
@@ -958,10 +994,81 @@ FlutterEngineResult FlutterEngineRun(size_t version,
                                      FLUTTER_API_SYMBOL(FlutterEngine) *
                                          engine_out);
 
+//------------------------------------------------------------------------------
+/// @brief      Shuts down a Flutter engine instance. the engine handle is no
+///             longer valid for any calls in the embedder API after this point.
+///             Making additional calls with this handle is undefined behavior.
+///
+/// @note       This de-initializes the Flutter engine instance (via an implicit
+///             call to `FlutterEngineDeinitialize`) if necessary.
+///
+/// @param[in]  engine  The Flutter engine instance to collect.
+///
+/// @return     The result of the call to shutdown the Flutter engine instance.
+///
 FLUTTER_EXPORT
 FlutterEngineResult FlutterEngineShutdown(FLUTTER_API_SYMBOL(FlutterEngine)
                                               engine);
 
+//------------------------------------------------------------------------------
+/// @brief      Initialize a Flutter engine instance. This does not run the
+///             Flutter application code till the `FlutterEngineRunInitialized`
+///             call is made. Besides Flutter application code, no tasks are
+///             scheduled on embedder managed task runners either. This allows
+///             embedders providing custom task runners to the Flutter engine to
+///             obtain a handle to the Flutter engine before the engine can post
+///             tasks on these task runners.
+///
+/// @param[in]  version    The Flutter embedder API version. Must be
+///                        FLUTTER_ENGINE_VERSION.
+/// @param[in]  config     The renderer configuration.
+/// @param[in]  args       The Flutter project arguments.
+/// @param      user_data  A user data baton passed back to embedders in
+///                        callbacks.
+/// @param[out] engine_out The engine handle on successful engine creation.
+///
+/// @return     The result of the call to initialize the Flutter engine.
+///
+FLUTTER_EXPORT
+FlutterEngineResult FlutterEngineInitialize(size_t version,
+                                            const FlutterRendererConfig* config,
+                                            const FlutterProjectArgs* args,
+                                            void* user_data,
+                                            FLUTTER_API_SYMBOL(FlutterEngine) *
+                                                engine_out);
+
+//------------------------------------------------------------------------------
+/// @brief      Stops running the Flutter engine instance. After this call, the
+///             embedder is also guaranteed that no more calls to post tasks
+///             onto custom task runners specified by the embedder are made. The
+///             Flutter engine handle still needs to be collected via a call to
+///             `FlutterEngineShutdown`.
+///
+/// @param[in]  engine    The running engine instance to de-initialize.
+///
+/// @return     The result of the call to de-initialize the Flutter engine.
+///
+FLUTTER_EXPORT
+FlutterEngineResult FlutterEngineDeinitialize(FLUTTER_API_SYMBOL(FlutterEngine)
+                                                  engine);
+
+//------------------------------------------------------------------------------
+/// @brief      Runs an initialized engine instance. An engine can be
+///             initialized via `FlutterEngineInitialize`. An initialized
+///             instance can only be run once. During and after this call,
+///             custom task runners supplied by the embedder are expected to
+///             start servicing tasks.
+///
+/// @param[in]  engine  An initialized engine instance that has not previously
+///                     been run.
+///
+/// @return     The result of the call to run the initialized Flutter
+///             engine instance.
+///
+FLUTTER_EXPORT
+FlutterEngineResult FlutterEngineRunInitialized(
+    FLUTTER_API_SYMBOL(FlutterEngine) engine);
+
 FLUTTER_EXPORT
 FlutterEngineResult FlutterEngineSendWindowMetricsEvent(
     FLUTTER_API_SYMBOL(FlutterEngine) engine,

shell/platform/embedder/embedder_engine.cc

@@ -9,32 +9,73 @@
 
 namespace flutter {
 
+struct ShellArgs {
+  Settings settings;
+  Shell::CreateCallback<PlatformView> on_create_platform_view;
+  Shell::CreateCallback<Rasterizer> on_create_rasterizer;
+  ShellArgs(Settings p_settings,
+            Shell::CreateCallback<PlatformView> p_on_create_platform_view,
+            Shell::CreateCallback<Rasterizer> p_on_create_rasterizer)
+      : settings(std::move(p_settings)),
+        on_create_platform_view(std::move(p_on_create_platform_view)),
+        on_create_rasterizer(std::move(p_on_create_rasterizer)) {}
+};
+
 EmbedderEngine::EmbedderEngine(
     std::unique_ptr<EmbedderThreadHost> thread_host,
     flutter::TaskRunners task_runners,
     flutter::Settings settings,
+    RunConfiguration run_configuration,
     Shell::CreateCallback<PlatformView> on_create_platform_view,
     Shell::CreateCallback<Rasterizer> on_create_rasterizer,
     EmbedderExternalTextureGL::ExternalTextureCallback
         external_texture_callback)
     : thread_host_(std::move(thread_host)),
       task_runners_(task_runners),
-      shell_(Shell::Create(task_runners_,
-                           std::move(settings),
-                           on_create_platform_view,
-                           on_create_rasterizer)),
-      external_texture_callback_(external_texture_callback) {
-  if (!shell_) {
-    return;
+      run_configuration_(std::move(run_configuration)),
+      shell_args_(std::make_unique<ShellArgs>(std::move(settings),
+                                              on_create_platform_view,
+                                              on_create_rasterizer)),
+      external_texture_callback_(external_texture_callback) {}
+
+EmbedderEngine::~EmbedderEngine() = default;
+
+bool EmbedderEngine::LaunchShell() {
+  if (!shell_args_) {
+    FML_DLOG(ERROR) << "Invalid shell arguments.";
+    return false;
+  }
+
+  if (shell_) {
+    FML_DLOG(ERROR) << "Shell already initialized";
   }
 
-  is_valid_ = true;
+  shell_ = Shell::Create(task_runners_, shell_args_->settings,
+                         shell_args_->on_create_platform_view,
+                         shell_args_->on_create_rasterizer);
+
+  // Reset the args no matter what. We are never going to use them to initialize
+  // a shell again.
+  shell_args_.reset();
+
+  return IsValid();
 }
 
-EmbedderEngine::~EmbedderEngine() = default;
+bool EmbedderEngine::CollectShell() {
+  shell_.reset();
+  return IsValid();
+}
+
+bool EmbedderEngine::RunRootIsolate() {
+  if (!IsValid() || !run_configuration_.IsValid()) {
+    return false;
+  }
+  shell_->RunEngine(std::move(run_configuration_));
+  return true;
+}
 
 bool EmbedderEngine::IsValid() const {
-  return is_valid_;
+  return static_cast<bool>(shell_);
 }
 
 const TaskRunners& EmbedderEngine::GetTaskRunners() const {
@@ -59,14 +100,6 @@ bool EmbedderEngine::NotifyDestroyed() {
   return true;
 }
 
-bool EmbedderEngine::Run(RunConfiguration run_configuration) {
-  if (!IsValid() || !run_configuration.IsValid()) {
-    return false;
-  }
-  shell_->RunEngine(std::move(run_configuration));
-  return true;
-}
-
 bool EmbedderEngine::SetViewportMetrics(flutter::ViewportMetrics metrics) {
   if (!IsValid()) {
     return false;
@@ -187,6 +220,10 @@ bool EmbedderEngine::OnVsyncEvent(intptr_t baton,
 }
 
 bool EmbedderEngine::ReloadSystemFonts() {
+  if (!IsValid()) {
+    return false;
+  }
+
   return shell_->ReloadSystemFonts();
 }
 
@@ -200,7 +237,10 @@ bool EmbedderEngine::PostRenderThreadTask(fml::closure task) {
 }
 
 bool EmbedderEngine::RunTask(const FlutterTask* task) {
-  if (!IsValid() || task == nullptr) {
+  // The shell doesn't need to be running or valid for access to the thread
+  // host. This is why there is no `IsValid` check here. This allows embedders
+  // to perform custom task runner interop before the shell is running.
+  if (task == nullptr) {
     return false;
   }
   return thread_host_->PostTask(reinterpret_cast<int64_t>(task->runner),