Define HighResTimeStamp, HighResDuration (facebook#51254)

hoxyq · facebook-github-bot · commit 481edaf9a527 · 2025-05-15T02:39:48.000-07:00
Summary: # Changelog: [Internal] Defines single timestamp abstraction that will be used in C++ layer of React Native core: Key primitives include: - `HighResTimeStamp`: A class representing a specific point in time with high precision. - `HighResDuration`: A class representing a duration of time with high precision. Right now, all these just encapsulate `std::chrono::steady_clock` with no extra custom logic. We might revisit this in a future, once we decide to add support for [`Performance.timeOrigin`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/timeOrigin). This diff also adds a `README.md` documentation file with a brief summary of the `react/timing` module. Reviewed By: rubennorte Differential Revision: D72796412
diff --git a/packages/react-native/ReactCommon/react/timing/__docs__/README.md b/packages/react-native/ReactCommon/react/timing/__docs__/README.md
@@ -0,0 +1,89 @@
+# React Native Timing
+
+[🏠 Home](../../../../../../__docs__/README.md)
+
+This directory contains the shared C++ implementation of high-resolution timing
+primitives for React Native. These primitives provide precise time measurement
+capabilities that align with Web standards while being optimized for the React
+Native environment.
+
+## 🚀 Usage
+
+The timing primitives in this module are primarily used by internal React Native
+systems that require precise time measurements. The monotonic clock is used for
+these primitives: they should be used for measuring time intervals. These
+primitives should not be used for wall times. They are not expected to be used
+directly by application developers but serve as foundational components for
+various React Native features.
+
+Key primitives include:
+
+- `HighResTimeStamp`: A class representing a specific point in time with high
+  precision.
+- `HighResDuration`: A class representing a duration of time with high
+  precision.
+
+These primitives support various operations:
+
+```cpp
+// Getting the current high-resolution timestamp
+auto start = HighResTimeStamp::now();
+
+// Creating durations
+auto duration = HighResDuration::fromNanoseconds(100);
+
+// Arithmetic operations
+auto later = start + duration;
+auto elapsed = later - start;
+
+// Converting to absolute time units of highest precision
+auto end = HighResTimeStamp::now();
+int64_t nanoseconds = (end - start).toNanoseconds();
+
+// Converting to DOMHighResTimeStamp (for JavaScript interoperability)
+double jsTimeValue = now.toDOMHighResTimeStampSinceArbitraryEpoch();
+```
+
+## 📐 Design
+
+The timing primitives are designed to align with Web standards while leveraging
+C++'s type system and the performance characteristics of native code. The
+implementation uses `std::chrono` internally but provides a more specialized
+interface tailored to React Native's needs.
+
+### HighResTimeStamp
+
+This class represents a specific point in time with high precision. It
+encapsulates a `std::chrono::steady_clock::time_point` and provides methods to:
+
+- Convert to `DOMHighResTimeStamp` for JavaScript interoperability.
+- Perform arithmetic operations with durations.
+- Compare with other timestamps.
+
+### HighResDuration
+
+This class represents a duration of time with high precision. It encapsulates a
+`std::chrono::duration` and provides methods to:
+
+- Convert to `DOMHighResTimeStamp` for JavaScript interoperability.
+- Convert to an absolute number of nanoseconds.
+- Perform arithmetic operations.
+- Compare with other durations.
+
+## 🔗 Relationship with other systems
+
+### Used by
+
+- [Event Loop](../../renderer/runtimescheduler/__docs__/README.md): Uses timing
+  primitives for measuring task execution times and scheduling.
+- Web Performance API: Timing primitives are used to implement performance
+  measurement APIs like `PerformanceObserver` entries (e.g., `longtask` and
+  `event`).
+- React Native DevTools: The timing primitives integrate with the React Native
+  DevTools tracing infrastructure to report the timing of tasks and events.
+
+### Related to
+
+- Web timing APIs: The timing primitives are designed to be compatible with Web
+  timing concepts, making it easier to implement Web-compatible APIs in React
+  Native.
diff --git a/packages/react-native/ReactCommon/react/timing/primitives.h b/packages/react-native/ReactCommon/react/timing/primitives.h
@@ -30,4 +30,274 @@ inline DOMHighResTimeStamp chronoToDOMHighResTimeStamp(
   return chronoToDOMHighResTimeStamp(timePoint.time_since_epoch());
 }
 
+class HighResDuration;
+class HighResTimeStamp;
+
+/*
+ * A class representing a duration of time with high precision.
+ *
+ * @see __docs__/README.md for more information.
+ */
+class HighResDuration {
+  friend class HighResTimeStamp;
+  friend constexpr HighResDuration operator-(
+      const HighResTimeStamp& lhs,
+      const HighResTimeStamp& rhs);
+  friend constexpr HighResTimeStamp operator+(
+      const HighResTimeStamp& lhs,
+      const HighResDuration& rhs);
+  friend constexpr HighResTimeStamp operator-(
+      const HighResTimeStamp& lhs,
+      const HighResDuration& rhs);
+
+ public:
+  constexpr HighResDuration()
+      : chronoDuration_(std::chrono::steady_clock::duration()) {}
+
+  static constexpr HighResDuration zero() {
+    return HighResDuration(std::chrono::steady_clock::duration::zero());
+  }
+
+  static constexpr HighResDuration fromChrono(
+      std::chrono::steady_clock::duration chronoDuration) {
+    return HighResDuration(chronoDuration);
+  }
+
+  static constexpr HighResDuration fromNanoseconds(int64_t units) {
+    return HighResDuration(std::chrono::nanoseconds(units));
+  }
+
+  static constexpr HighResDuration fromMilliseconds(int64_t units) {
+    return HighResDuration(std::chrono::milliseconds(units));
+  }
+
+  constexpr int64_t toNanoseconds() const {
+    return std::chrono::duration_cast<std::chrono::nanoseconds>(chronoDuration_)
+        .count();
+  }
+
+  // @see https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp
+  static constexpr HighResDuration fromDOMHighResTimeStamp(double units) {
+    auto nanoseconds = static_cast<int64_t>(units * 1e6);
+    return fromNanoseconds(nanoseconds);
+  }
+
+  // @see https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp
+  constexpr double toDOMHighResTimeStamp() const {
+    return static_cast<std::chrono::duration<double, std::milli>>(
+               chronoDuration_)
+        .count();
+  }
+
+  constexpr HighResDuration operator+(const HighResDuration& rhs) const {
+    return HighResDuration(chronoDuration_ + rhs.chronoDuration_);
+  }
+
+  constexpr HighResDuration operator+(
+      const std::chrono::steady_clock::duration& rhs) const {
+    return HighResDuration(chronoDuration_ + rhs);
+  }
+
+  constexpr HighResDuration operator-(const HighResDuration& rhs) const {
+    return HighResDuration(chronoDuration_ - rhs.chronoDuration_);
+  }
+
+  constexpr HighResDuration operator-(
+      const std::chrono::steady_clock::duration& rhs) const {
+    return HighResDuration(chronoDuration_ - rhs);
+  }
+
+  constexpr HighResDuration& operator+=(const HighResDuration& rhs) {
+    chronoDuration_ += rhs.chronoDuration_;
+    return *this;
+  }
+
+  constexpr HighResDuration& operator+=(
+      const std::chrono::steady_clock::duration& rhs) {
+    chronoDuration_ += rhs;
+    return *this;
+  }
+
+  constexpr HighResDuration& operator-=(const HighResDuration& rhs) {
+    chronoDuration_ -= rhs.chronoDuration_;
+    return *this;
+  }
+
+  constexpr HighResDuration& operator-=(
+      const std::chrono::steady_clock::duration& rhs) {
+    chronoDuration_ -= rhs;
+    return *this;
+  }
+
+  constexpr bool operator==(const HighResDuration& rhs) const {
+    return chronoDuration_ == rhs.chronoDuration_;
+  }
+
+  constexpr bool operator==(
+      const std::chrono::steady_clock::duration& rhs) const {
+    return chronoDuration_ == rhs;
+  }
+
+  constexpr bool operator!=(const HighResDuration& rhs) const {
+    return chronoDuration_ != rhs.chronoDuration_;
+  }
+
+  constexpr bool operator!=(
+      const std::chrono::steady_clock::duration& rhs) const {
+    return chronoDuration_ != rhs;
+  }
+
+  constexpr bool operator<(const HighResDuration& rhs) const {
+    return chronoDuration_ < rhs.chronoDuration_;
+  }
+
+  constexpr bool operator<(
+      const std::chrono::steady_clock::duration& rhs) const {
+    return chronoDuration_ < rhs;
+  }
+
+  constexpr bool operator<=(const HighResDuration& rhs) const {
+    return chronoDuration_ <= rhs.chronoDuration_;
+  }
+
+  constexpr bool operator<=(
+      const std::chrono::steady_clock::duration& rhs) const {
+    return chronoDuration_ <= rhs;
+  }
+
+  constexpr bool operator>(const HighResDuration& rhs) const {
+    return chronoDuration_ > rhs.chronoDuration_;
+  }
+
+  constexpr bool operator>(
+      const std::chrono::steady_clock::duration& rhs) const {
+    return chronoDuration_ > rhs;
+  }
+
+  constexpr bool operator>=(const HighResDuration& rhs) const {
+    return chronoDuration_ >= rhs.chronoDuration_;
+  }
+
+  constexpr bool operator>=(
+      const std::chrono::steady_clock::duration& rhs) const {
+    return chronoDuration_ >= rhs;
+  }
+
+  constexpr operator std::chrono::steady_clock::duration() const {
+    return chronoDuration_;
+  }
+
+ private:
+  explicit constexpr HighResDuration(
+      std::chrono::steady_clock::duration chronoDuration)
+      : chronoDuration_(chronoDuration) {}
+
+  std::chrono::steady_clock::duration chronoDuration_;
+};
+
+/*
+ * A class representing a specific point in time with high precision.
+ *
+ * @see __docs__/README.md for more information.
+ */
+class HighResTimeStamp {
+  friend constexpr HighResDuration operator-(
+      const HighResTimeStamp& lhs,
+      const HighResTimeStamp& rhs);
+  friend constexpr HighResTimeStamp operator+(
+      const HighResTimeStamp& lhs,
+      const HighResDuration& rhs);
+  friend constexpr HighResTimeStamp operator-(
+      const HighResTimeStamp& lhs,
+      const HighResDuration& rhs);
+
+ public:
+  HighResTimeStamp() noexcept
+      : chronoTimePoint_(std::chrono::steady_clock::now()) {}
+
+  static constexpr HighResTimeStamp now() noexcept {
+    return HighResTimeStamp(std::chrono::steady_clock::now());
+  }
+
+  static constexpr HighResTimeStamp min() noexcept {
+    return HighResTimeStamp(std::chrono::steady_clock::time_point::min());
+  }
+
+  static constexpr HighResTimeStamp max() noexcept {
+    return HighResTimeStamp(std::chrono::steady_clock::time_point::max());
+  }
+
+  // @see https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp
+  static constexpr HighResTimeStamp fromDOMHighResTimeStamp(double units) {
+    auto nanoseconds = static_cast<int64_t>(units * 1e6);
+    return HighResTimeStamp(std::chrono::steady_clock::time_point(
+        std::chrono::nanoseconds(nanoseconds)));
+  }
+
+  // @see https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp
+  constexpr double toDOMHighResTimeStamp() const {
+    return HighResDuration(chronoTimePoint_.time_since_epoch())
+        .toDOMHighResTimeStamp();
+  }
+
+  constexpr bool operator==(const HighResTimeStamp& rhs) const {
+    return chronoTimePoint_ == rhs.chronoTimePoint_;
+  }
+
+  constexpr bool operator!=(const HighResTimeStamp& rhs) const {
+    return chronoTimePoint_ != rhs.chronoTimePoint_;
+  }
+
+  constexpr bool operator<(const HighResTimeStamp& rhs) const {
+    return chronoTimePoint_ < rhs.chronoTimePoint_;
+  }
+
+  constexpr bool operator<=(const HighResTimeStamp& rhs) const {
+    return chronoTimePoint_ <= rhs.chronoTimePoint_;
+  }
+
+  constexpr bool operator>(const HighResTimeStamp& rhs) const {
+    return chronoTimePoint_ > rhs.chronoTimePoint_;
+  }
+
+  constexpr bool operator>=(const HighResTimeStamp& rhs) const {
+    return chronoTimePoint_ >= rhs.chronoTimePoint_;
+  }
+
+  constexpr HighResTimeStamp& operator+=(const HighResDuration& rhs) {
+    chronoTimePoint_ += rhs.chronoDuration_;
+    return *this;
+  }
+
+  constexpr HighResTimeStamp& operator-=(const HighResDuration& rhs) {
+    chronoTimePoint_ -= rhs.chronoDuration_;
+    return *this;
+  }
+
+ private:
+  explicit constexpr HighResTimeStamp(
+      std::chrono::steady_clock::time_point chronoTimePoint)
+      : chronoTimePoint_(chronoTimePoint) {}
+
+  std::chrono::steady_clock::time_point chronoTimePoint_;
+};
+
+inline constexpr HighResDuration operator-(
+    const HighResTimeStamp& lhs,
+    const HighResTimeStamp& rhs) {
+  return HighResDuration(lhs.chronoTimePoint_ - rhs.chronoTimePoint_);
+}
+
+inline constexpr HighResTimeStamp operator+(
+    const HighResTimeStamp& lhs,
+    const HighResDuration& rhs) {
+  return HighResTimeStamp(lhs.chronoTimePoint_ + rhs.chronoDuration_);
+}
+
+inline constexpr HighResTimeStamp operator-(
+    const HighResTimeStamp& lhs,
+    const HighResDuration& rhs) {
+  return HighResTimeStamp(lhs.chronoTimePoint_ - rhs.chronoDuration_);
+}
+
 } // namespace facebook::react
diff --git a/packages/react-native/ReactCommon/react/timing/tests/PrimitivesTest.cpp b/packages/react-native/ReactCommon/react/timing/tests/PrimitivesTest.cpp
