feat(ext/node): add createHistogram to node:perf_hooks (#34003)

Adds the missing `createHistogram(options)` export to `node:perf_hooks`,
along with the `Histogram` / `RecordableHistogram` classes Node.js
exposes from this module.

The following Node compat tests are now enabled and passing:

- `parallel/test-perf-hooks-histogram.js`
- `parallel/test-perf-hooks-histogram-fast-calls.js`
- `parallel/test-perf-hooks-timerify-histogram-async.mjs`
- `parallel/test-perf-hooks-timerify-histogram-sync.mjs`

Closes #34001

---------

Co-authored-by: lunadogbot <lunadogbot@users.noreply.github.com>
Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>

Author: 3 people

Cargo.lock

@@ -223,6 +223,7 @@ fqdn = "0.5"
 futures = "0.3.31"
 glob = "0.3.1"
 h2 = "0.4.6"
+hdrhistogram = "7.5"
 hickory-proto = "0.25.2"
 hickory-resolver = { version = "0.25.2", features = ["tokio", "serde"] }
 hickory-server = "0.25.2"

Cargo.toml

@@ -756,7 +756,7 @@ declare module "perf_hooks" {
          * The maximum recorded event loop delay.
          * v17.4.0, v16.14.0
          */
-        readonly maxBigInt: number;
+        readonly maxBigInt: bigint;
         /**
          * The mean of the recorded event loop delays.
          * @since v11.10.0

cli/tsc/dts/node/perf_hooks.d.cts

@@ -41,6 +41,7 @@ deno_process.workspace = true
 deno_tls.workspace = true
 deno_whoami.workspace = true
 h2.workspace = true
+hdrhistogram.workspace = true
 http.workspace = true
 http-body-util.workspace = true
 hyper.workspace = true

ext/node/Cargo.toml

@@ -391,6 +391,7 @@ deno_core::extension!(deno_node,
   ],
   objects = [
     ops::perf_hooks::EldHistogram,
+    ops::perf_hooks::BaseHistogram,
     ops::handle_wrap::AsyncWrap,
     ops::handle_wrap::HandleWrap,
     ops::wasi::WasiContext,

ext/node/lib.rs

@@ -5,12 +5,18 @@ use std::cell::RefCell;
 
 use deno_core::GarbageCollected;
 use deno_core::op2;
+use hdrhistogram::Histogram;
+
+const EMPTY_HISTOGRAM_MIN: u64 = i64::MAX as u64;
 
 #[derive(Debug, thiserror::Error, deno_error::JsError)]
 pub enum PerfHooksError {
   #[class(generic)]
   #[error(transparent)]
   TokioEld(#[from] tokio_eld::Error),
+  #[class(generic)]
+  #[error(transparent)]
+  HistogramCreation(#[from] hdrhistogram::errors::CreationError),
 }
 
 pub struct EldHistogram {
@@ -147,3 +153,280 @@ impl EldHistogram {
     self.eld.borrow().stdev()
   }
 }
+
+// Backs the user-facing `RecordableHistogram` returned by
+// `perf_hooks.createHistogram()`. Wraps an `hdrhistogram::Histogram<u64>`
+// configured with caller-supplied bounds, plus the bookkeeping needed for
+// `recordDelta()` and the `exceeds` counter (incremented when a recorded
+// value overflows the histogram's `highest` bound).
+pub struct BaseHistogram {
+  inner: RefCell<Histogram<u64>>,
+  highest: u64,
+  exceeds: Cell<u64>,
+  added_out_of_range: Cell<u64>,
+  prev_delta_ns: Cell<Option<u64>>,
+}
+
+// SAFETY: we're sure this can be GCed
+unsafe impl GarbageCollected for BaseHistogram {
+  fn trace(&self, _visitor: &mut deno_core::v8::cppgc::Visitor) {}
+
+  fn get_name(&self) -> &'static std::ffi::CStr {
+    c"BaseHistogram"
+  }
+}
+
+fn now_ns() -> u64 {
+  // Match Node's `process.hrtime` clock domain — monotonic nanoseconds.
+  use std::time::Instant;
+  thread_local! {
+    static ORIGIN: Instant = Instant::now();
+  }
+  ORIGIN.with(|origin| origin.elapsed().as_nanos() as u64)
+}
+
+#[op2]
+impl BaseHistogram {
+  // Creates a `RecordableHistogram` with the given bounds and significant
+  // figures. Mirrors the behavior of Node's `createHistogram(options)`.
+  //
+  // Caller is responsible for validating bounds; this just forwards them to
+  // `hdrhistogram::Histogram::new_with_bounds`.
+  #[constructor]
+  #[cppgc]
+  pub fn new(
+    #[bigint] lowest: u64,
+    #[bigint] highest: u64,
+    #[smi] figures: u32,
+  ) -> Result<BaseHistogram, PerfHooksError> {
+    let inner =
+      Histogram::<u64>::new_with_bounds(lowest, highest, figures as u8)?;
+    Ok(BaseHistogram {
+      inner: RefCell::new(inner),
+      highest,
+      exceeds: Cell::new(0),
+      added_out_of_range: Cell::new(0),
+      prev_delta_ns: Cell::new(None),
+    })
+  }
+
+  // Records a value into the histogram. If the value exceeds the configured
+  // `highest`, increments the `exceeds` counter instead of erroring.
+  #[fast]
+  fn record(&self, #[bigint] value: u64) {
+    if value > self.highest {
+      self.exceeds.set(self.exceeds.get().saturating_add(1));
+      return;
+    }
+    let mut h = self.inner.borrow_mut();
+    if h.record(value).is_err() {
+      self.exceeds.set(self.exceeds.get().saturating_add(1));
+    }
+  }
+
+  // Records the nanoseconds elapsed since the previous call to recordDelta.
+  // The first call seeds the timestamp without recording (matches Node).
+  #[fast]
+  fn record_delta(&self) {
+    let now = now_ns();
+    if let Some(prev) = self.prev_delta_ns.get() {
+      let delta = now.saturating_sub(prev);
+      if delta > self.highest {
+        self.exceeds.set(self.exceeds.get().saturating_add(1));
+        self.prev_delta_ns.set(Some(now));
+        return;
+      }
+      let mut h = self.inner.borrow_mut();
+      if h.record(delta).is_err() {
+        self.exceeds.set(self.exceeds.get().saturating_add(1));
+      }
+    }
+    self.prev_delta_ns.set(Some(now));
+  }
+
+  // Adds counts from another histogram into this one.
+  #[fast]
+  fn add(&self, #[cppgc] other: &BaseHistogram) {
+    let other_h = other.inner.borrow();
+    let mut h = self.inner.borrow_mut();
+    let mut added_out_of_range = self.added_out_of_range.get();
+    for v in other_h.iter_recorded() {
+      if v.value_iterated_to() > self.highest
+        || h
+          .record_n(v.value_iterated_to(), v.count_at_value())
+          .is_err()
+      {
+        added_out_of_range =
+          added_out_of_range.saturating_add(v.count_at_value());
+      }
+    }
+    self.added_out_of_range.set(added_out_of_range);
+    self
+      .exceeds
+      .set(self.exceeds.get().saturating_add(other.exceeds.get()));
+  }
+
+  #[fast]
+  fn reset(&self) {
+    self.inner.borrow_mut().reset();
+    self.exceeds.set(0);
+    self.added_out_of_range.set(0);
+    self.prev_delta_ns.set(None);
+  }
+
+  #[fast]
+  #[number]
+  fn percentile(&self, percentile: f64) -> u64 {
+    self.inner.borrow().value_at_percentile(percentile)
+  }
+
+  #[fast]
+  #[bigint]
+  fn percentile_big_int(&self, percentile: f64) -> u64 {
+    self.inner.borrow().value_at_percentile(percentile)
+  }
+
+  // Returns the percentile distribution as a flat `[percentile, value, ...]`
+  // array. The JS layer turns it into a `Map`. We iterate the recorded values
+  // and emit one entry per distinct value.
+  //
+  // Values are bounded by `highest` (validated to fit in a JS safe integer by
+  // the createHistogram caller), so emitting them as f64 is lossless.
+  #[serde]
+  fn percentiles(&self) -> Vec<f64> {
+    let h = self.inner.borrow();
+    let mut out = Vec::new();
+    if h.is_empty() {
+      out.push(100.0);
+      out.push(0.0);
+      return out;
+    }
+    out.push(0.0);
+    out.push(h.min() as f64);
+    if h.len() > 1 {
+      let max = h.max();
+      let mut percentile = 50.0;
+      while percentile < 100.0 {
+        let value = h.value_at_percentile(percentile);
+        out.push(percentile);
+        out.push(value as f64);
+        if value >= max {
+          break;
+        }
+        percentile += (100.0 - percentile) / 2.0;
+      }
+    }
+    out.push(100.0);
+    out.push(h.max() as f64);
+    out
+  }
+
+  // Same shape as `percentiles`; the JS layer re-wraps the value entries as
+  // BigInt when exposing them through `percentilesBigInt`.
+  #[serde]
+  fn percentiles_big_int(&self) -> Vec<f64> {
+    let h = self.inner.borrow();
+    let mut out = Vec::new();
+    if h.is_empty() {
+      out.push(100.0);
+      out.push(0.0);
+      return out;
+    }
+    out.push(0.0);
+    out.push(h.min() as f64);
+    if h.len() > 1 {
+      let max = h.max();
+      let mut percentile = 50.0;
+      while percentile < 100.0 {
+        let value = h.value_at_percentile(percentile);
+        out.push(percentile);
+        out.push(value as f64);
+        if value >= max {
+          break;
+        }
+        percentile += (100.0 - percentile) / 2.0;
+      }
+    }
+    out.push(100.0);
+    out.push(h.max() as f64);
+    out
+  }
+
+  #[getter]
+  #[number]
+  fn count(&self) -> u64 {
+    self
+      .inner
+      .borrow()
+      .len()
+      .saturating_add(self.added_out_of_range.get())
+  }
+
+  #[getter]
+  #[bigint]
+  fn count_big_int(&self) -> u64 {
+    self
+      .inner
+      .borrow()
+      .len()
+      .saturating_add(self.added_out_of_range.get())
+  }
+
+  #[getter]
+  #[number]
+  fn min(&self) -> u64 {
+    let h = self.inner.borrow();
+    if h.is_empty() {
+      EMPTY_HISTOGRAM_MIN
+    } else {
+      h.min()
+    }
+  }
+
+  #[getter]
+  #[bigint]
+  fn min_big_int(&self) -> u64 {
+    let h = self.inner.borrow();
+    if h.is_empty() {
+      EMPTY_HISTOGRAM_MIN
+    } else {
+      h.min()
+    }
+  }
+
+  #[getter]
+  #[number]
+  fn max(&self) -> u64 {
+    self.inner.borrow().max()
+  }
+
+  #[getter]
+  #[bigint]
+  fn max_big_int(&self) -> u64 {
+    self.inner.borrow().max()
+  }
+
+  #[getter]
+  fn mean(&self) -> f64 {
+    let h = self.inner.borrow();
+    if h.is_empty() { f64::NAN } else { h.mean() }
+  }
+
+  #[getter]
+  fn stddev(&self) -> f64 {
+    let h = self.inner.borrow();
+    if h.is_empty() { f64::NAN } else { h.stdev() }
+  }
+
+  #[getter]
+  #[number]
+  fn exceeds(&self) -> u64 {
+    self.exceeds.get()
+  }
+
+  #[getter]
+  #[bigint]
+  fn exceeds_big_int(&self) -> u64 {
+    self.exceeds.get()
+  }
+}