[Impeller] when decoding image on iOS, block on command buffer scheduling and log gpu errors. (flutter#169378)

Attempted fix for flutter#166668 .
Plan is to ask for testing once rolled into g3 since we weren't given a
repro.

Explaination: we can only submit command buffers to the metal command
queue when the device is in the foreground. push notifications
temporarily wake up the app and can trigger images to begin decoding.
This decoding can fail, possibly due to the app re-backgrounding. In
theory, the sync switch should prevent this from happening - but because
we don't actually block on the scheduling of the command buffer there is
technically a race that can happen.

Add the ability to block submission on scheduling for metal. note that
other graphics APIs do not have a distinction for commited vs scheduled
and so it no-ops for them.


See
https://developer.apple.com/documentation/metal/preparing-your-metal-app-to-run-in-the-background

> When UIKit calls your app delegate’s
[applicationDidEnterBackground(_:)](https://developer.apple.com/documentation/UIKit/UIApplicationDelegate/applicationDidEnterBackground(_:))
method, make sure Metal has scheduled all command buffers you’ve already
committed before your app returns control to the system. ... Finish
encoding commands to render the frame and commit the command buffer,
then call
[waitUntilScheduled()](https://developer.apple.com/documentation/metal/mtlcommandbuffer/waituntilscheduled()).

Author: Jonah Williams

engine/src/flutter/impeller/renderer/backend/gles/command_buffer_gles.cc

@@ -29,7 +29,8 @@ bool CommandBufferGLES::IsValid() const {
 }
 
 // |CommandBuffer|
-bool CommandBufferGLES::OnSubmitCommands(CompletionCallback callback) {
+bool CommandBufferGLES::OnSubmitCommands(bool block_on_schedule,
+                                         CompletionCallback callback) {
   const auto result = reactor_->React();
   if (callback) {
     callback(result ? CommandBuffer::Status::kCompleted

engine/src/flutter/impeller/renderer/backend/gles/command_buffer_gles.h

@@ -32,7 +32,8 @@ class CommandBufferGLES final : public CommandBuffer {
   bool IsValid() const override;
 
   // |CommandBuffer|
-  bool OnSubmitCommands(CompletionCallback callback) override;
+  bool OnSubmitCommands(bool block_on_schedule,
+                        CompletionCallback callback) override;
 
   // |CommandBuffer|
   void OnWaitUntilCompleted() override;

engine/src/flutter/impeller/renderer/backend/metal/command_buffer_mtl.h

@@ -34,7 +34,8 @@ class CommandBufferMTL final : public CommandBuffer {
   bool IsValid() const override;
 
   // |CommandBuffer|
-  bool OnSubmitCommands(CompletionCallback callback) override;
+  bool OnSubmitCommands(bool block_on_schedule,
+                        CompletionCallback callback) override;
 
   // |CommandBuffer|
   void OnWaitUntilCompleted() override;

engine/src/flutter/impeller/renderer/backend/metal/command_buffer_mtl.mm

@@ -162,7 +162,8 @@ static bool LogMTLCommandBufferErrorIfPresent(id<MTLCommandBuffer> buffer) {
   return CommandBufferMTL::Status::kError;
 }
 
-bool CommandBufferMTL::OnSubmitCommands(CompletionCallback callback) {
+bool CommandBufferMTL::OnSubmitCommands(bool block_on_schedule,
+                                        CompletionCallback callback) {
   auto context = context_.lock();
   if (!context) {
     return false;
@@ -182,6 +183,9 @@ static bool LogMTLCommandBufferErrorIfPresent(id<MTLCommandBuffer> buffer) {
   }
 
   [buffer_ commit];
+  if (block_on_schedule) {
+    [buffer_ waitUntilScheduled];
+  }
 
   buffer_ = nil;
   return true;

engine/src/flutter/impeller/renderer/backend/vulkan/command_buffer_vk.cc

@@ -43,7 +43,8 @@ bool CommandBufferVK::IsValid() const {
   return true;
 }
 
-bool CommandBufferVK::OnSubmitCommands(CompletionCallback callback) {
+bool CommandBufferVK::OnSubmitCommands(bool block_on_schedule,
+                                       CompletionCallback callback) {
   FML_UNREACHABLE()
 }
 

engine/src/flutter/impeller/renderer/backend/vulkan/command_buffer_vk.h

@@ -98,7 +98,8 @@ class CommandBufferVK final
   bool IsValid() const override;
 
   // |CommandBuffer|
-  bool OnSubmitCommands(CompletionCallback callback) override;
+  bool OnSubmitCommands(bool block_on_schedule,
+                        CompletionCallback callback) override;
 
   // |CommandBuffer|
   void OnWaitUntilCompleted() override;

engine/src/flutter/impeller/renderer/backend/vulkan/command_queue_vk.cc

@@ -22,7 +22,8 @@ CommandQueueVK::~CommandQueueVK() = default;
 
 fml::Status CommandQueueVK::Submit(
     const std::vector<std::shared_ptr<CommandBuffer>>& buffers,
-    const CompletionCallback& completion_callback) {
+    const CompletionCallback& completion_callback,
+    bool block_on_schedule) {
   if (buffers.empty()) {
     return fml::Status(fml::StatusCode::kInvalidArgument,
                        "No command buffers provided.");

engine/src/flutter/impeller/renderer/backend/vulkan/command_queue_vk.h

@@ -17,9 +17,9 @@ class CommandQueueVK : public CommandQueue {
 
   ~CommandQueueVK() override;
 
-  fml::Status Submit(
-      const std::vector<std::shared_ptr<CommandBuffer>>& buffers,
-      const CompletionCallback& completion_callback = {}) override;
+  fml::Status Submit(const std::vector<std::shared_ptr<CommandBuffer>>& buffers,
+                     const CompletionCallback& completion_callback = {},
+                     bool block_on_schedule = false) override;
 
  private:
   std::weak_ptr<ContextVK> context_;

engine/src/flutter/impeller/renderer/command_buffer.cc

@@ -15,19 +15,20 @@ CommandBuffer::CommandBuffer(std::weak_ptr<const Context> context)
 
 CommandBuffer::~CommandBuffer() = default;
 
-bool CommandBuffer::SubmitCommands(const CompletionCallback& callback) {
+bool CommandBuffer::SubmitCommands(bool block_on_schedule,
+                                   const CompletionCallback& callback) {
   if (!IsValid()) {
     // Already committed or was never valid. Either way, this is caller error.
     if (callback) {
       callback(Status::kError);
     }
     return false;
   }
-  return OnSubmitCommands(callback);
+  return OnSubmitCommands(block_on_schedule, callback);
 }
 
-bool CommandBuffer::SubmitCommands() {
-  return SubmitCommands(nullptr);
+bool CommandBuffer::SubmitCommands(bool block_on_schedule) {
+  return SubmitCommands(block_on_schedule, nullptr);
 }
 
 void CommandBuffer::WaitUntilCompleted() {

engine/src/flutter/impeller/renderer/command_buffer.h

@@ -107,7 +107,11 @@ class CommandBuffer {
 
   virtual std::shared_ptr<BlitPass> OnCreateBlitPass() = 0;
 
-  [[nodiscard]] virtual bool OnSubmitCommands(CompletionCallback callback) = 0;
+  /// @brief Submit the command buffer to the GPU for execution.
+  ///
+  /// See also: [SubmitCommands].
+  [[nodiscard]] virtual bool OnSubmitCommands(bool block_on_schedule,
+                                              CompletionCallback callback) = 0;
 
   virtual void OnWaitUntilCompleted() = 0;
 
@@ -124,12 +128,15 @@ class CommandBuffer {
   ///             performed immediately on the calling thread.
   ///
   ///             A command buffer may only be committed once.
-  ///
+  /// @param[in]  block_on_schedule  If true, this function will not return
+  ///             until the command buffer has been scheduled. This only impacts
+  ///             the Metal backend.
   /// @param[in]  callback  The completion callback.
   ///
-  [[nodiscard]] bool SubmitCommands(const CompletionCallback& callback);
+  [[nodiscard]] bool SubmitCommands(bool block_on_schedule,
+                                    const CompletionCallback& callback);
 
-  [[nodiscard]] bool SubmitCommands();
+  [[nodiscard]] bool SubmitCommands(bool block_on_schedule);
 
   CommandBuffer(const CommandBuffer&) = delete;