Introducing Timeline: A time-travel debugging tool (cross-platform part)

Summary:
This is a core part of the Timeline feature (aka Time Travel Debugger). With these new primitives, any external library can initiate "saving" all the previous interface changes (commits) and unwind to any previous one (in order to introspect and validate visual side-effects).

The next diff in the stack will implement UI for this feature integrated into Debug menu on iOS.

Changelog: [Internal] Fabric-specific internal change.

Reviewed By: sammy-SC

Differential Revision: D25926660

fbshipit-source-id: 2e5f6892351d3053db8f64c1cf6ff445b0867ad7

Author: shergin

ReactCommon/react/renderer/timeline/BUCK

@@ -0,0 +1,84 @@
+load("@fbsource//tools/build_defs/apple:flag_defs.bzl", "get_preprocessor_flags_for_build_mode")
+load(
+    "//tools/build_defs/oss:rn_defs.bzl",
+    "ANDROID",
+    "APPLE",
+    "CXX",
+    "fb_xplat_cxx_test",
+    "get_apple_compiler_flags",
+    "get_apple_inspector_flags",
+    "react_native_xplat_target",
+    "rn_xplat_cxx_library",
+    "subdir_glob",
+)
+
+APPLE_COMPILER_FLAGS = get_apple_compiler_flags()
+
+rn_xplat_cxx_library(
+    name = "timeline",
+    srcs = glob(
+        ["**/*.cpp"],
+        exclude = glob(["tests/**/*.cpp"]),
+    ),
+    headers = glob(
+        ["**/*.h"],
+        exclude = glob(["tests/**/*.h"]),
+    ),
+    header_namespace = "",
+    exported_headers = subdir_glob(
+        [
+            ("", "*.h"),
+        ],
+        prefix = "react/renderer/timeline",
+    ),
+    compiler_flags = [
+        "-fexceptions",
+        "-frtti",
+        "-std=c++14",
+        "-Wall",
+    ],
+    fbobjc_compiler_flags = APPLE_COMPILER_FLAGS,
+    fbobjc_labels = ["supermodule:ios/isolation/infra.react_native"],
+    fbobjc_preprocessor_flags = get_preprocessor_flags_for_build_mode() + get_apple_inspector_flags(),
+    force_static = True,
+    macosx_tests_override = [],
+    platforms = (ANDROID, APPLE, CXX),
+    preprocessor_flags = [
+        "-DLOG_TAG=\"ReactNative\"",
+        "-DWITH_FBSYSTRACE=1",
+    ],
+    tests = [":tests"],
+    visibility = ["PUBLIC"],
+    deps = [
+        "fbsource//xplat/fbsystrace:fbsystrace",
+        "fbsource//xplat/folly:headers_only",
+        "fbsource//xplat/folly:memory",
+        "fbsource//xplat/folly:molly",
+        "//third-party/glog:glog",
+        react_native_xplat_target("react/utils:utils"),
+        react_native_xplat_target("react/renderer/debug:debug"),
+        react_native_xplat_target("react/renderer/core:core"),
+        react_native_xplat_target("react/renderer/components/root:root"),
+        react_native_xplat_target("react/renderer/mounting:mounting"),
+        react_native_xplat_target("react/renderer/uimanager:uimanager"),
+    ],
+)
+
+fb_xplat_cxx_test(
+    name = "tests",
+    srcs = glob(["tests/**/*.cpp"]),
+    headers = glob(["tests/**/*.h"]),
+    compiler_flags = [
+        "-fexceptions",
+        "-frtti",
+        "-std=c++14",
+        "-Wall",
+    ],
+    contacts = ["oncall+react_native@xmail.facebook.com"],
+    platforms = (ANDROID, APPLE, CXX),
+    deps = [
+        "fbsource//xplat/folly:molly",
+        "fbsource//xplat/third-party/gmock:gtest",
+        ":timeline",
+    ],
+)

ReactCommon/react/renderer/timeline/Timeline.cpp

@@ -0,0 +1,120 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include "Timeline.h"
+
+#include <react/renderer/uimanager/UIManager.h>
+
+namespace facebook {
+namespace react {
+
+Timeline::Timeline(ShadowTree const &shadowTree) : shadowTree_(&shadowTree) {
+  record(shadowTree.getCurrentRevision().rootShadowNode);
+};
+
+#pragma mark - Public
+
+SurfaceId Timeline::getSurfaceId() const noexcept {
+  return shadowTree_->getSurfaceId();
+}
+
+void Timeline::pause() const noexcept {
+  std::lock_guard<std::recursive_mutex> lock(mutex_);
+  assert(!paused_ && "");
+  paused_ = true;
+}
+
+void Timeline::resume() const noexcept {
+  std::lock_guard<std::recursive_mutex> lock(mutex_);
+
+  if (snapshots_.size() > 0) {
+    rewind(snapshots_.at(snapshots_.size() - 1));
+  }
+
+  assert(paused_ && "");
+  paused_ = false;
+}
+
+bool Timeline::isPaused() const noexcept {
+  std::lock_guard<std::recursive_mutex> lock(mutex_);
+  return paused_;
+}
+
+TimelineFrame::List Timeline::getFrames() const noexcept {
+  std::lock_guard<std::recursive_mutex> lock(mutex_);
+
+  auto frames = TimelineFrame::List{};
+  frames.reserve(snapshots_.size());
+  for (auto const &snapshot : snapshots_) {
+    frames.push_back(snapshot.getFrame());
+  }
+  return frames;
+}
+
+TimelineFrame Timeline::getCurrentFrame() const noexcept {
+  assert(snapshots_.size() > currentSnapshotIndex_);
+  return snapshots_.at(currentSnapshotIndex_).getFrame();
+}
+
+void Timeline::rewind(TimelineFrame const &frame) const noexcept {
+  std::lock_guard<std::recursive_mutex> lock(mutex_);
+  rewind(snapshots_.at(frame.getIndex()));
+}
+
+RootShadowNode::Unshared Timeline::shadowTreeWillCommit(
+    ShadowTree const &shadowTree,
+    RootShadowNode::Shared const &oldRootShadowNode,
+    RootShadowNode::Unshared const &newRootShadowNode) const noexcept {
+  std::lock_guard<std::recursive_mutex> lock(mutex_);
+
+  if (rewinding_) {
+    return newRootShadowNode;
+  }
+
+  record(newRootShadowNode);
+
+  if (paused_) {
+    return nullptr;
+  }
+
+  return newRootShadowNode;
+}
+
+#pragma mark - Private & Internal
+
+void Timeline::record(
+    RootShadowNode::Shared const &rootShadowNode) const noexcept {
+  auto index = (int)snapshots_.size();
+  snapshots_.push_back(TimelineSnapshot{rootShadowNode, index});
+
+  if (!paused_) {
+    currentSnapshotIndex_ = index;
+  }
+}
+
+void Timeline::rewind(TimelineSnapshot const &snapshot) const noexcept {
+  std::lock_guard<std::recursive_mutex> lock(mutex_);
+
+  currentSnapshotIndex_ = snapshot.getFrame().getIndex();
+
+  assert(!rewinding_ && "");
+  rewinding_ = true;
+
+  auto rootShadowNode = snapshot.getRootShadowNode();
+
+  shadowTree_->commit(
+      [&](RootShadowNode const &oldRootShadowNode) -> RootShadowNode::Unshared {
+        return std::static_pointer_cast<RootShadowNode>(
+            rootShadowNode->ShadowNode::clone({}));
+      });
+
+  assert(rewinding_ && "");
+  rewinding_ = false;
+}
+
+} // namespace react
+} // namespace facebook

ReactCommon/react/renderer/timeline/Timeline.h

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <memory>
+#include <vector>
+
+#include <better/mutex.h>
+
+#include <react/renderer/core/ReactPrimitives.h>
+#include <react/renderer/timeline/TimelineSnapshot.h>
+#include <react/renderer/uimanager/UIManagerCommitHook.h>
+
+namespace facebook {
+namespace react {
+
+class UIManager;
+
+class Timeline final {
+  friend class TimelineHandler;
+  friend class TimelineController;
+
+ public:
+  Timeline(ShadowTree const &shadowTree);
+
+ private:
+#pragma mark - Private methods to be used by `TimelineHandler`.
+
+  void pause() const noexcept;
+  void resume() const noexcept;
+  bool isPaused() const noexcept;
+  TimelineFrame::List getFrames() const noexcept;
+  TimelineFrame getCurrentFrame() const noexcept;
+  void rewind(TimelineFrame const &frame) const noexcept;
+  SurfaceId getSurfaceId() const noexcept;
+
+#pragma mark - Private methods to be used by `TimelineController`.
+
+  RootShadowNode::Unshared shadowTreeWillCommit(
+      ShadowTree const &shadowTree,
+      RootShadowNode::Shared const &oldRootShadowNode,
+      RootShadowNode::Unshared const &newRootShadowNode) const noexcept;
+
+#pragma mark - Private & Internal
+
+  void record(RootShadowNode::Shared const &rootShadowNode) const noexcept;
+  void rewind(TimelineSnapshot const &snapshot) const noexcept;
+
+  mutable std::recursive_mutex mutex_;
+  mutable ShadowTree const *shadowTree_{nullptr};
+  mutable int currentSnapshotIndex_{0};
+  mutable TimelineSnapshot::List snapshots_{};
+  mutable bool paused_{false};
+  mutable bool rewinding_{false};
+};
+
+} // namespace react
+} // namespace facebook

ReactCommon/react/renderer/timeline/TimelineController.cpp

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include "TimelineController.h"
+
+#include <react/renderer/mounting/ShadowTree.h>
+#include <react/renderer/uimanager/UIManager.h>
+
+namespace facebook {
+namespace react {
+
+TimelineHandler TimelineController::enable(SurfaceId surfaceId) const {
+  assert(uiManager_);
+
+  auto shadowTreePtr = (ShadowTree const *){};
+
+  uiManager_->getShadowTreeRegistry().visit(
+      surfaceId,
+      [&](ShadowTree const &shadowTree) { shadowTreePtr = &shadowTree; });
+
+  assert(shadowTreePtr);
+
+  {
+    std::unique_lock<better::shared_mutex> lock(timelinesMutex_);
+
+    auto timeline = std::make_unique<Timeline>(*shadowTreePtr);
+    auto handler = TimelineHandler{*timeline};
+    timelines_.emplace(surfaceId, std::move(timeline));
+    return handler;
+  }
+}
+
+void TimelineController::disable(TimelineHandler &&handler) const {
+  std::unique_lock<better::shared_mutex> lock(timelinesMutex_);
+
+  auto iterator = timelines_.find(handler.getSurfaceId());
+  assert(iterator != timelines_.end());
+  timelines_.erase(iterator);
+  handler.release();
+}
+
+void TimelineController::commitHookWasRegistered(
+    UIManager const &uiManager) const noexcept {
+  uiManager_ = &uiManager;
+}
+
+void TimelineController::commitHookWasUnregistered(
+    UIManager const &uiManager) const noexcept {
+  uiManager_ = nullptr;
+}
+
+RootShadowNode::Unshared TimelineController::shadowTreeWillCommit(
+    ShadowTree const &shadowTree,
+    RootShadowNode::Shared const &oldRootShadowNode,
+    RootShadowNode::Unshared const &newRootShadowNode) const noexcept {
+  std::shared_lock<better::shared_mutex> lock(timelinesMutex_);
+
+  assert(uiManager_ && "`uiManager_` must not be `nullptr`.");
+
+  lastUpdatedSurface_ = shadowTree.getSurfaceId();
+
+  auto iterator = timelines_.find(shadowTree.getSurfaceId());
+  if (iterator == timelines_.end()) {
+    return newRootShadowNode;
+  }
+
+  auto &timeline = *iterator->second;
+  return timeline.shadowTreeWillCommit(
+      shadowTree, oldRootShadowNode, newRootShadowNode);
+}
+
+} // namespace react
+} // namespace facebook