rename and add docs

Author: Kaushik Iska

shell/common/animator.cc

@@ -154,7 +154,7 @@ void Animator::Render(std::unique_ptr<flutter::LayerTree> layer_tree) {
                                 last_frame_target_time_);
   }
 
-  layer_tree_holder_->ReplaceIfNewer(std::move(layer_tree));
+  layer_tree_holder_->PushIfNewer(std::move(layer_tree));
   delegate_.OnAnimatorDraw(layer_tree_holder_, last_frame_target_time_);
 }
 

shell/common/layer_tree_holder.cc

@@ -6,12 +6,16 @@
 
 namespace flutter {
 
-std::unique_ptr<LayerTree> LayerTreeHolder::Get() {
+LayerTreeHolder::LayerTreeHolder() = default;
+
+LayerTreeHolder::~LayerTreeHolder() = default;
+
+std::unique_ptr<LayerTree> LayerTreeHolder::Pop() {
   std::scoped_lock lock(layer_tree_mutex);
   return std::move(layer_tree_);
 }
 
-void LayerTreeHolder::ReplaceIfNewer(
+void LayerTreeHolder::PushIfNewer(
     std::unique_ptr<LayerTree> proposed_layer_tree) {
   std::scoped_lock lock(layer_tree_mutex);
   if (!layer_tree_ ||

shell/common/layer_tree_holder.h

@@ -11,17 +11,37 @@
 
 namespace flutter {
 
+/**
+ * @brief Holds the next `flutter::LayerTree` that needs to be rasterized. The
+ * accesses to `LayerTreeHolder` are thread safe. This is important as this
+ * component is accessed from both the UI and the Raster threads.
+ *
+ * A typical flow of events through this component would be:
+ *  1. `flutter::Animator` pushed a layer tree to be rendered during each
+ * `Animator::Render` call.
+ *  2. `flutter::Rasterizer::Draw` consumes the pushed layer tree via `Pop`.
+ *
+ * It is important to note that if a layer tree held by this class is yet to be
+ * consumed, it can be overriden by a newer layer tree produced by the
+ * `Animator`. The newness of the layer tree is determined by the target time.
+ */
 class LayerTreeHolder {
  public:
-  LayerTreeHolder() = default;
+  LayerTreeHolder();
 
-  ~LayerTreeHolder() = default;
+  ~LayerTreeHolder();
 
+  /**
+   * @brief Checks if a layer tree is currently held.
+   *
+   * @return true is no layer tree is held.
+   * @return false if there is a layer tree waiting to be consumed.
+   */
   bool IsEmpty() const;
 
-  std::unique_ptr<LayerTree> Get();
+  [[nodiscard]] std::unique_ptr<LayerTree> Pop();
 
-  void ReplaceIfNewer(std::unique_ptr<LayerTree> proposed_layer_tree);
+  void PushIfNewer(std::unique_ptr<LayerTree> proposed_layer_tree);
 
  private:
   mutable std::mutex layer_tree_mutex;

shell/common/layer_tree_holder_unittests.cc

@@ -23,9 +23,9 @@ TEST(LayerTreeHolder, PutOneAndGet) {
   LayerTreeHolder layer_tree_holder;
   const auto frame_size = SkISize::Make(64, 64);
   auto layer_tree = std::make_unique<LayerTree>(frame_size, 100.0f, 1.0f);
-  layer_tree_holder.ReplaceIfNewer(std::move(layer_tree));
+  layer_tree_holder.PushIfNewer(std::move(layer_tree));
   ASSERT_FALSE(layer_tree_holder.IsEmpty());
-  const auto stored = layer_tree_holder.Get();
+  const auto stored = layer_tree_holder.Pop();
   ASSERT_EQ(stored->frame_size(), frame_size);
   ASSERT_TRUE(layer_tree_holder.IsEmpty());
 }
@@ -39,14 +39,14 @@ TEST(LayerTreeHolder, PutMultiGetsLatest) {
   const auto frame_size_1 = SkISize::Make(64, 64);
   auto layer_tree_1 = std::make_unique<LayerTree>(frame_size_1, 100.0f, 1.0f);
   layer_tree_1->RecordBuildTime(build_begin, target_time_1);
-  layer_tree_holder.ReplaceIfNewer(std::move(layer_tree_1));
+  layer_tree_holder.PushIfNewer(std::move(layer_tree_1));
 
   const auto frame_size_2 = SkISize::Make(128, 128);
   auto layer_tree_2 = std::make_unique<LayerTree>(frame_size_2, 100.0f, 1.0f);
   layer_tree_2->RecordBuildTime(build_begin, target_time_2);
-  layer_tree_holder.ReplaceIfNewer(std::move(layer_tree_2));
+  layer_tree_holder.PushIfNewer(std::move(layer_tree_2));
 
-  const auto stored = layer_tree_holder.Get();
+  const auto stored = layer_tree_holder.Pop();
   ASSERT_EQ(stored->frame_size(), frame_size_2);
   ASSERT_TRUE(layer_tree_holder.IsEmpty());
 }
@@ -60,14 +60,14 @@ TEST(LayerTreeHolder, RetainsOlderIfNewerFrameHasEarlierTargetTime) {
   const auto frame_size_1 = SkISize::Make(64, 64);
   auto layer_tree_1 = std::make_unique<LayerTree>(frame_size_1, 100.0f, 1.0f);
   layer_tree_1->RecordBuildTime(build_begin, target_time_1);
-  layer_tree_holder.ReplaceIfNewer(std::move(layer_tree_1));
+  layer_tree_holder.PushIfNewer(std::move(layer_tree_1));
 
   const auto frame_size_2 = SkISize::Make(128, 128);
   auto layer_tree_2 = std::make_unique<LayerTree>(frame_size_2, 100.0f, 1.0f);
   layer_tree_2->RecordBuildTime(build_begin, target_time_2);
-  layer_tree_holder.ReplaceIfNewer(std::move(layer_tree_2));
+  layer_tree_holder.PushIfNewer(std::move(layer_tree_2));
 
-  const auto stored = layer_tree_holder.Get();
+  const auto stored = layer_tree_holder.Pop();
   ASSERT_EQ(stored->frame_size(), frame_size_1);
   ASSERT_TRUE(layer_tree_holder.IsEmpty());
 }

shell/common/rasterizer.cc

@@ -119,14 +119,14 @@ void Rasterizer::Draw(std::shared_ptr<LayerTreeHolder> layer_tree_holder) {
   }
   FML_DCHECK(task_runners_.GetRasterTaskRunner()->RunsTasksOnCurrentThread());
 
-  std::unique_ptr<LayerTree> layer_tree = layer_tree_holder->Get();
+  std::unique_ptr<LayerTree> layer_tree = layer_tree_holder->Pop();
   RasterStatus raster_status =
       layer_tree ? DoDraw(std::move(layer_tree)) : RasterStatus::kFailed;
 
   // Merging the thread as we know the next `Draw` should be run on the platform
   // thread.
   if (raster_status == RasterStatus::kResubmit) {
-    layer_tree_holder->ReplaceIfNewer(std::move(resubmitted_layer_tree_));
+    layer_tree_holder->PushIfNewer(std::move(resubmitted_layer_tree_));
     auto* external_view_embedder = surface_->GetExternalViewEmbedder();
     FML_DCHECK(external_view_embedder != nullptr)
         << "kResubmit is an invalid raster status without external view "