Define HighResTimeStamp, HighResTimeDuration, HighResTimeClock (#51254)

hoxyq · facebook-github-bot · commit d883108df267 · 2025-05-12T10:17:16.000-07:00
Summary: Pull Request resolved: #51254 # 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. - `HighResTimeDuration`: A class representing a duration of time with high precision. - `HighResTimeClock`: A class providing a monotonic clock that won't be adjusted. 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. 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,95 @@
+# 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. They are not typically 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.
+- `HighResTimeDuration`: A class representing a duration of time with high
+  precision.
+- `HighResTimeClock`: A class providing a monotonic clock that won't be
+  adjusted.
+
+These primitives support various operations:
+
+```cpp
+// Getting the current high-resolution timestamp
+auto now = HighResTimeClock::now();
+
+// Creating durations
+auto duration = HighResTimeDuration(std::chrono::milliseconds(100));
+
+// Arithmetic operations
+auto later = now + duration;
+auto elapsed = later - now;
+
+// Converting to different time units with high precision
+int64_t nanoseconds = now.toNanoseconds();
+int64_t microseconds = now.toMicroseconds();
+int64_t milliseconds = now.toMilliseconds();
+
+// Converting to DOMHighResTimeStamp (for JavaScript interoperability)
+double jsTimeValue = now.toDOMHighResTimeStamp();
+```
+
+## 📐 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.
+
+### HighResTimeDuration
+
+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.
+- Perform arithmetic operations.
+- Compare with other durations.
+
+### HighResTimeClock
+
+This class provides access to a monotonic clock that will never be adjusted.
+It's based on `std::chrono::steady_clock` and ensures consistent time
+measurements even if the system clock is adjusted.
+
+## 🔗 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,262 @@ inline DOMHighResTimeStamp chronoToDOMHighResTimeStamp(
   return chronoToDOMHighResTimeStamp(timePoint.time_since_epoch());
 }
 
+class HighResTimeDuration;
+class HighResTimeStamp;
+
+/*
+ * A class representing a duration of time with high precision.
+ *
+ * @see __docs__/README.md for more information.
+ */
+class HighResTimeDuration {
+  friend class HighResTimeStamp;
+  friend HighResTimeDuration operator-(
+      const HighResTimeStamp& lhs,
+      const HighResTimeStamp& rhs);
+  friend HighResTimeStamp operator+(
+      const HighResTimeStamp& lhs,
+      const HighResTimeDuration& rhs);
+  friend HighResTimeStamp operator-(
+      const HighResTimeStamp& lhs,
+      const HighResTimeDuration& rhs);
+
+ public:
+  HighResTimeDuration()
+      : chronoDuration_(std::chrono::steady_clock::duration()) {}
+  /* implicit */ HighResTimeDuration(std::chrono::nanoseconds nanoseconds)
+      : chronoDuration_(nanoseconds) {}
+  /* implicit */ HighResTimeDuration(std::chrono::microseconds microseconds)
+      : chronoDuration_(microseconds) {}
+  /* implicit */ HighResTimeDuration(std::chrono::milliseconds milliseconds)
+      : chronoDuration_(milliseconds) {}
+  /* implicit */ HighResTimeDuration(std::chrono::seconds seconds)
+      : chronoDuration_(seconds) {}
+
+  int64_t toNanoseconds() const {
+    return std::chrono::duration_cast<std::chrono::nanoseconds>(chronoDuration_)
+        .count();
+  }
+
+  int64_t toMicroseconds() const {
+    return std::chrono::duration_cast<std::chrono::microseconds>(
+               chronoDuration_)
+        .count();
+  }
+
+  double toMicrosecondsWithPrecision() const {
+    return static_cast<std::chrono::duration<double, std::micro>>(
+               chronoDuration_)
+        .count();
+  }
+
+  int64_t toMilliseconds() const {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(
+               chronoDuration_)
+        .count();
+  }
+
+  double toMillisecondsWithPrecision() const {
+    return static_cast<std::chrono::duration<double, std::milli>>(
+               chronoDuration_)
+        .count();
+  }
+
+  int64_t toSeconds() const {
+    return std::chrono::duration_cast<std::chrono::seconds>(chronoDuration_)
+        .count();
+  }
+
+  double toSecondsWithPrecision() const {
+    return static_cast<std::chrono::duration<double>>(chronoDuration_).count();
+  }
+
+  double toDOMHighResTimeStamp() const {
+    return toMillisecondsWithPrecision();
+  }
+
+  HighResTimeDuration operator+(const HighResTimeDuration& rhs) const {
+    return {chronoDuration_ + rhs.chronoDuration_};
+  }
+
+  HighResTimeDuration operator-(const HighResTimeDuration& rhs) const {
+    return {chronoDuration_ - rhs.chronoDuration_};
+  }
+
+  HighResTimeDuration& operator+=(const HighResTimeDuration& rhs) {
+    chronoDuration_ += rhs.chronoDuration_;
+    return *this;
+  }
+
+  HighResTimeDuration& operator-=(const HighResTimeDuration& rhs) {
+    chronoDuration_ -= rhs.chronoDuration_;
+    return *this;
+  }
+
+  bool operator==(const HighResTimeDuration& rhs) const {
+    return chronoDuration_ == rhs.chronoDuration_;
+  }
+
+  bool operator!=(const HighResTimeDuration& rhs) const {
+    return chronoDuration_ != rhs.chronoDuration_;
+  }
+
+  bool operator<(const HighResTimeDuration& rhs) const {
+    return chronoDuration_ < rhs.chronoDuration_;
+  }
+
+  bool operator<=(const HighResTimeDuration& rhs) const {
+    return chronoDuration_ <= rhs.chronoDuration_;
+  }
+
+  bool operator>(const HighResTimeDuration& rhs) const {
+    return chronoDuration_ > rhs.chronoDuration_;
+  }
+
+  bool operator>=(const HighResTimeDuration& rhs) const {
+    return chronoDuration_ >= rhs.chronoDuration_;
+  }
+
+ private:
+  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 class HighResTimeClock;
+  friend HighResTimeDuration operator-(
+      const HighResTimeStamp& lhs,
+      const HighResTimeStamp& rhs);
+  friend HighResTimeStamp operator+(
+      const HighResTimeStamp& lhs,
+      const HighResTimeDuration& rhs);
+  friend HighResTimeStamp operator-(
+      const HighResTimeStamp& lhs,
+      const HighResTimeDuration& rhs);
+
+ public:
+  HighResTimeStamp()
+      : chronoTimeStamp_(std::chrono::steady_clock::time_point()) {}
+  explicit HighResTimeStamp(HighResTimeDuration duration)
+      : chronoTimeStamp_(duration.chronoDuration_) {}
+  /* implicit */ HighResTimeStamp(std::chrono::nanoseconds nanoseconds)
+      : chronoTimeStamp_(nanoseconds) {}
+  /* implicit */ HighResTimeStamp(std::chrono::microseconds microseconds)
+      : chronoTimeStamp_(microseconds) {}
+  /* implicit */ HighResTimeStamp(std::chrono::milliseconds milliseconds)
+      : chronoTimeStamp_(milliseconds) {}
+  /* implicit */ HighResTimeStamp(std::chrono::seconds seconds)
+      : chronoTimeStamp_(seconds) {}
+
+  HighResTimeDuration toDuration() const {
+    return {chronoTimeStamp_.time_since_epoch()};
+  }
+
+  int64_t toNanoseconds() const {
+    return toDuration().toNanoseconds();
+  }
+
+  int64_t toMicroseconds() const {
+    return toDuration().toMicroseconds();
+  }
+
+  double toMicrosecondsWithPrecision() const {
+    return toDuration().toMicrosecondsWithPrecision();
+  }
+
+  int64_t toMilliseconds() const {
+    return toDuration().toMilliseconds();
+  }
+
+  double toMillisecondsWithPrecision() const {
+    return toDuration().toMillisecondsWithPrecision();
+  }
+
+  int64_t toSeconds() const {
+    return toDuration().toSeconds();
+  }
+
+  double toSecondsWithPrecision() const {
+    return toDuration().toSecondsWithPrecision();
+  }
+
+  double toDOMHighResTimeStamp() const {
+    return toDuration().toDOMHighResTimeStamp();
+  }
+
+  bool operator==(const HighResTimeStamp& rhs) const {
+    return chronoTimeStamp_ == rhs.chronoTimeStamp_;
+  }
+
+  bool operator!=(const HighResTimeStamp& rhs) const {
+    return chronoTimeStamp_ != rhs.chronoTimeStamp_;
+  }
+
+  bool operator<(const HighResTimeStamp& rhs) const {
+    return chronoTimeStamp_ < rhs.chronoTimeStamp_;
+  }
+
+  bool operator<=(const HighResTimeStamp& rhs) const {
+    return chronoTimeStamp_ <= rhs.chronoTimeStamp_;
+  }
+
+  bool operator>(const HighResTimeStamp& rhs) const {
+    return chronoTimeStamp_ > rhs.chronoTimeStamp_;
+  }
+
+  bool operator>=(const HighResTimeStamp& rhs) const {
+    return chronoTimeStamp_ >= rhs.chronoTimeStamp_;
+  }
+
+  HighResTimeStamp& operator+=(const HighResTimeDuration& rhs) {
+    chronoTimeStamp_ += rhs.chronoDuration_;
+    return *this;
+  }
+
+  HighResTimeStamp& operator-=(const HighResTimeDuration& rhs) {
+    chronoTimeStamp_ -= rhs.chronoDuration_;
+    return *this;
+  }
+
+ private:
+  explicit HighResTimeStamp(std::chrono::steady_clock::time_point timeStamp)
+      : chronoTimeStamp_(timeStamp) {}
+
+  std::chrono::steady_clock::time_point chronoTimeStamp_;
+};
+
+/*
+ * A class providing a monotonic clock that won't be adjusted.
+ *
+ * @see __docs__/README.md for more information.
+ */
+class HighResTimeClock {
+ public:
+  static HighResTimeStamp now() noexcept {
+    return HighResTimeStamp(std::chrono::steady_clock::now());
+  }
+};
+
+inline HighResTimeDuration operator-(
+    const HighResTimeStamp& lhs,
+    const HighResTimeStamp& rhs) {
+  return {lhs.chronoTimeStamp_ - rhs.chronoTimeStamp_};
+}
+
+inline HighResTimeStamp operator+(
+    const HighResTimeStamp& lhs,
+    const HighResTimeDuration& rhs) {
+  return HighResTimeStamp(lhs.chronoTimeStamp_ + rhs.chronoDuration_);
+}
+
+inline HighResTimeStamp operator-(
+    const HighResTimeStamp& lhs,
+    const HighResTimeDuration& rhs) {
+  return HighResTimeStamp(lhs.chronoTimeStamp_ - 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
