Allow embedders to specify their own task runner interfaces. (flutter…

…#8273)

Currently, all Flutter threads are managed by the engine itself. This works for
all threads except the platform thread. On this thread, the engine cannot see
the underlying event multiplexing mechanism. Using the new task runner
interfaces, the engine can relinquish the task of setting up the event
multiplexing mechanism and instead have the embedder provide one for it during
setup.

This scheme is only wired up for the platform thread. But, the eventual goal
is to expose this message loop interoperability for all threads.

ci/licenses_golden/licenses_flutter

@@ -675,12 +675,17 @@ FILE: ../../../flutter/shell/platform/embedder/embedder_engine.h
 FILE: ../../../flutter/shell/platform/embedder/embedder_external_texture_gl.cc
 FILE: ../../../flutter/shell/platform/embedder/embedder_external_texture_gl.h
 FILE: ../../../flutter/shell/platform/embedder/embedder_include.c
+FILE: ../../../flutter/shell/platform/embedder/embedder_safe_access.h
 FILE: ../../../flutter/shell/platform/embedder/embedder_surface.cc
 FILE: ../../../flutter/shell/platform/embedder/embedder_surface.h
 FILE: ../../../flutter/shell/platform/embedder/embedder_surface_gl.cc
 FILE: ../../../flutter/shell/platform/embedder/embedder_surface_gl.h
 FILE: ../../../flutter/shell/platform/embedder/embedder_surface_software.cc
 FILE: ../../../flutter/shell/platform/embedder/embedder_surface_software.h
+FILE: ../../../flutter/shell/platform/embedder/embedder_task_runner.cc
+FILE: ../../../flutter/shell/platform/embedder/embedder_task_runner.h
+FILE: ../../../flutter/shell/platform/embedder/embedder_thread_host.cc
+FILE: ../../../flutter/shell/platform/embedder/embedder_thread_host.h
 FILE: ../../../flutter/shell/platform/embedder/fixtures/a11y_main.dart
 FILE: ../../../flutter/shell/platform/embedder/fixtures/simple_main.dart
 FILE: ../../../flutter/shell/platform/embedder/platform_view_embedder.cc

fml/task_runner.h

@@ -17,6 +17,8 @@ class MessageLoopImpl;
 
 class TaskRunner : public fml::RefCountedThreadSafe<TaskRunner> {
  public:
+  virtual ~TaskRunner();
+
   virtual void PostTask(fml::closure task);
 
   virtual void PostTaskForTime(fml::closure task, fml::TimePoint target_time);
@@ -25,8 +27,6 @@ class TaskRunner : public fml::RefCountedThreadSafe<TaskRunner> {
 
   virtual bool RunsTasksOnCurrentThread();
 
-  virtual ~TaskRunner();
-
   static void RunNowOrPostTask(fml::RefPtr<fml::TaskRunner> runner,
                                fml::closure task);
 

shell/platform/embedder/BUILD.gn

@@ -22,12 +22,17 @@ source_set("embedder") {
     "embedder_external_texture_gl.cc",
     "embedder_external_texture_gl.h",
     "embedder_include.c",
+    "embedder_safe_access.h",
     "embedder_surface.cc",
     "embedder_surface.h",
     "embedder_surface_gl.cc",
     "embedder_surface_gl.h",
     "embedder_surface_software.cc",
     "embedder_surface_software.h",
+    "embedder_task_runner.cc",
+    "embedder_task_runner.h",
+    "embedder_thread_host.cc",
+    "embedder_thread_host.h",
     "platform_view_embedder.cc",
     "platform_view_embedder.h",
     "vsync_waiter_embedder.cc",

shell/platform/embedder/embedder.cc

@@ -21,10 +21,6 @@ extern const intptr_t kPlatformStrongDillSize;
 #endif  // FLUTTER_RUNTIME_MODE == FLUTTER_RUNTIME_MODE_DEBUG
 }
 
-#include "flutter/shell/platform/embedder/embedder.h"
-
-#include <type_traits>
-
 #include "flutter/assets/directory_asset_bundle.h"
 #include "flutter/common/task_runners.h"
 #include "flutter/fml/command_line.h"
@@ -38,18 +34,11 @@ extern const intptr_t kPlatformStrongDillSize;
 #include "flutter/shell/common/switches.h"
 #include "flutter/shell/platform/embedder/embedder.h"
 #include "flutter/shell/platform/embedder/embedder_engine.h"
+#include "flutter/shell/platform/embedder/embedder_safe_access.h"
+#include "flutter/shell/platform/embedder/embedder_task_runner.h"
+#include "flutter/shell/platform/embedder/embedder_thread_host.h"
 #include "flutter/shell/platform/embedder/platform_view_embedder.h"
 
-#define SAFE_ACCESS(pointer, member, default_value)                      \
-  ([=]() {                                                               \
-    if (offsetof(std::remove_pointer<decltype(pointer)>::type, member) + \
-            sizeof(pointer->member) <=                                   \
-        pointer->struct_size) {                                          \
-      return pointer->member;                                            \
-    }                                                                    \
-    return static_cast<decltype(pointer->member)>((default_value));      \
-  })()
-
 static FlutterEngineResult LogEmbedderError(FlutterEngineResult code,
                                             const char* name,
                                             const char* function,
@@ -408,20 +397,6 @@ FlutterEngineResult FlutterEngineRun(size_t version,
     };
   }
 
-  // Create a thread host with the current thread as the platform thread and all
-  // other threads managed.
-  shell::ThreadHost thread_host("io.flutter", shell::ThreadHost::Type::GPU |
-                                                  shell::ThreadHost::Type::IO |
-                                                  shell::ThreadHost::Type::UI);
-  fml::MessageLoop::EnsureInitializedForCurrentThread();
-  blink::TaskRunners task_runners(
-      "io.flutter",
-      fml::MessageLoop::GetCurrent().GetTaskRunner(),  // platform
-      thread_host.gpu_thread->GetTaskRunner(),         // gpu
-      thread_host.ui_thread->GetTaskRunner(),          // ui
-      thread_host.io_thread->GetTaskRunner()           // io
-  );
-
   shell::PlatformViewEmbedder::UpdateSemanticsNodesCallback
       update_semantics_nodes_callback = nullptr;
   if (SAFE_ACCESS(args, update_semantics_node_callback, nullptr) != nullptr) {
@@ -602,6 +577,23 @@ FlutterEngineResult FlutterEngineRun(size_t version,
     }
   }
 
+  auto thread_host =
+      shell::EmbedderThreadHost::CreateEmbedderOrEngineManagedThreadHost(
+          SAFE_ACCESS(args, custom_task_runners, nullptr));
+
+  if (!thread_host || !thread_host->IsValid()) {
+    FML_LOG(ERROR) << "Could not setup or infer thread configuration to run "
+                      "the Flutter engine on.";
+    return LOG_EMBEDDER_ERROR(kInvalidArguments);
+  }
+
+  auto task_runners = thread_host->GetTaskRunners();
+
+  if (!task_runners.IsValid()) {
+    FML_LOG(ERROR) << "Task runner configuration specified is invalid.";
+    return LOG_EMBEDDER_ERROR(kInvalidArguments);
+  }
+
   // Step 1: Create the engine.
   auto embedder_engine =
       std::make_unique<shell::EmbedderEngine>(std::move(thread_host),    //
@@ -940,3 +932,18 @@ FlutterEngineResult FlutterEnginePostRenderThreadTask(FlutterEngine engine,
              ? kSuccess
              : LOG_EMBEDDER_ERROR(kInternalInconsistency);
 }
+
+uint64_t FlutterEngineGetCurrentTime() {
+  return fml::TimePoint::Now().ToEpochDelta().ToNanoseconds();
+}
+
+FlutterEngineResult FlutterEngineRunTask(FlutterEngine engine,
+                                         const FlutterTask* task) {
+  if (engine == nullptr) {
+    return LOG_EMBEDDER_ERROR(kInvalidArguments);
+  }
+
+  return reinterpret_cast<shell::EmbedderEngine*>(engine)->RunTask(task)
+             ? kSuccess
+             : LOG_EMBEDDER_ERROR(kInvalidArguments);
+}

shell/platform/embedder/embedder.h

@@ -447,6 +447,52 @@ typedef void (*FlutterUpdateSemanticsCustomActionCallback)(
     const FlutterSemanticsCustomAction* /* semantics custom action */,
     void* /* user data */);
 
+typedef struct _FlutterTaskRunner* FlutterTaskRunner;
+
+typedef struct {
+  FlutterTaskRunner runner;
+  uint64_t task;
+} FlutterTask;
+
+typedef void (*FlutterTaskRunnerPostTaskCallback)(
+    FlutterTask /* task */,
+    uint64_t /* target time nanos */,
+    void* /* user data */);
+
+// An interface used by the Flutter engine to execute tasks at the target time
+// on a specified thread. There should be a 1-1 relationship between a thread
+// and a task runner. It is undefined behavior to run a task on a thread that is
+// not associated with its task runner.
+typedef struct {
+  // The size of this struct. Must be sizeof(FlutterTaskRunnerDescription).
+  size_t struct_size;
+  void* user_data;
+  // May be called from any thread. Should return true if tasks posted on the
+  // calling thread will be run on that same thread.
+  //
+  // This field is required.
+  BoolCallback runs_task_on_current_thread_callback;
+  // May be called from any thread. The given task should be executed by the
+  // embedder on the thread associated with that task runner by calling
+  // |FlutterEngineRunTask| at the given target time. The system monotonic clock
+  // should be used for the target time. The target time is the absolute time
+  // from epoch (NOT a delta) at which the task must be returned back to the
+  // engine on the correct thread. If the embedder needs to calculate a delta,
+  // |FlutterEngineGetCurrentTime| may be called and the difference used as the
+  // delta.
+  //
+  // This field is required.
+  FlutterTaskRunnerPostTaskCallback post_task_callback;
+} 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.
+  const FlutterTaskRunnerDescription* platform_task_runner;
+} FlutterCustomTaskRunners;
+
 typedef struct {
   // The size of this struct. Must be sizeof(FlutterProjectArgs).
   size_t struct_size;
@@ -572,6 +618,11 @@ typedef struct {
   // away. Usually, this is done using the `@pragma('vm:entry-point')`
   // decoration.
   const char* custom_dart_entrypoint;
+
+  // Typically the Flutter engine create and manages its internal threads. This
+  // optional argument allows for the specification of task runner interfaces to
+  // event loops managed by the embedder on threads it creates.
+  const FlutterCustomTaskRunners* custom_task_runners;
 } FlutterProjectArgs;
 
 FLUTTER_EXPORT
@@ -715,6 +766,19 @@ FlutterEngineResult FlutterEnginePostRenderThreadTask(FlutterEngine engine,
                                                       VoidCallback callback,
                                                       void* callback_data);
 
+// Get the current time in nanoseconds from the clock used by the flutter
+// engine. This is the system monotonic clock.
+FLUTTER_EXPORT
+uint64_t FlutterEngineGetCurrentTime();
+
+// Inform the engine to run the specified task. This task has been given to
+// the engine via the |FlutterTaskRunnerDescription.post_task_callback|. This
+// call must only be made at the target time specified in that callback. Running
+// the task before that time is undefined behavior.
+FLUTTER_EXPORT
+FlutterEngineResult FlutterEngineRunTask(FlutterEngine engine,
+                                         const FlutterTask* task);
+
 #if defined(__cplusplus)
 }  // extern "C"
 #endif

shell/platform/embedder/embedder_engine.cc

@@ -10,7 +10,7 @@
 namespace shell {
 
 EmbedderEngine::EmbedderEngine(
-    ThreadHost thread_host,
+    std::unique_ptr<EmbedderThreadHost> thread_host,
     blink::TaskRunners task_runners,
     blink::Settings settings,
     Shell::CreateCallback<PlatformView> on_create_platform_view,
@@ -23,7 +23,11 @@ EmbedderEngine::EmbedderEngine(
                            on_create_platform_view,
                            on_create_rasterizer)),
       external_texture_callback_(external_texture_callback) {
-  is_valid_ = shell_ != nullptr;
+  if (!shell_) {
+    return;
+  }
+
+  is_valid_ = true;
 }
 
 EmbedderEngine::~EmbedderEngine() = default;
@@ -212,4 +216,12 @@ bool EmbedderEngine::PostRenderThreadTask(fml::closure task) {
   return true;
 }
 
+bool EmbedderEngine::RunTask(const FlutterTask* task) {
+  if (!IsValid() || task == nullptr) {
+    return false;
+  }
+  return thread_host_->PostTask(reinterpret_cast<int64_t>(task->runner),
+                                task->task);
+}
+
 }  // namespace shell

shell/platform/embedder/embedder_engine.h

@@ -6,21 +6,23 @@
 #define FLUTTER_SHELL_PLATFORM_EMBEDDER_EMBEDDER_ENGINE_H_
 
 #include <memory>
+#include <unordered_map>
 
 #include "flutter/fml/macros.h"
 #include "flutter/shell/common/shell.h"
 #include "flutter/shell/common/thread_host.h"
 #include "flutter/shell/platform/embedder/embedder.h"
 #include "flutter/shell/platform/embedder/embedder_engine.h"
 #include "flutter/shell/platform/embedder/embedder_external_texture_gl.h"
+#include "flutter/shell/platform/embedder/embedder_thread_host.h"
 
 namespace shell {
 
 // The object that is returned to the embedder as an opaque pointer to the
 // instance of the Flutter engine.
 class EmbedderEngine {
  public:
-  EmbedderEngine(ThreadHost thread_host,
+  EmbedderEngine(std::unique_ptr<EmbedderThreadHost> thread_host,
                  blink::TaskRunners task_runners,
                  blink::Settings settings,
                  Shell::CreateCallback<PlatformView> on_create_platform_view,
@@ -65,8 +67,10 @@ class EmbedderEngine {
 
   bool PostRenderThreadTask(fml::closure task);
 
+  bool RunTask(const FlutterTask* task);
+
  private:
-  const ThreadHost thread_host_;
+  const std::unique_ptr<EmbedderThreadHost> thread_host_;
   std::unique_ptr<Shell> shell_;
   const EmbedderExternalTextureGL::ExternalTextureCallback
       external_texture_callback_;

shell/platform/embedder/embedder_safe_access.h

@@ -0,0 +1,20 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef FLUTTER_SHELL_PLATFORM_EMBEDDER_EMBEDDER_SAFE_ACCESS_H_
+#define FLUTTER_SHELL_PLATFORM_EMBEDDER_EMBEDDER_SAFE_ACCESS_H_
+
+#include <type_traits>
+
+#define SAFE_ACCESS(pointer, member, default_value)                      \
+  ([=]() {                                                               \
+    if (offsetof(std::remove_pointer<decltype(pointer)>::type, member) + \
+            sizeof(pointer->member) <=                                   \
+        pointer->struct_size) {                                          \
+      return pointer->member;                                            \
+    }                                                                    \
+    return static_cast<decltype(pointer->member)>((default_value));      \
+  })()
+
+#endif  // FLUTTER_SHELL_PLATFORM_EMBEDDER_EMBEDDER_SAFE_ACCESS_H_