Newtypes JsInstant and JsDuration to allow Boa, hosts and libraries a single (wall) clock type

[hansl]

Problem Statement

There is currently multiple types to represent time in the Boa Engine; utc_now() uses an i64 number of milliseconds since EPOCH, JsDate take that value and convert it into JavaScript dates and times, Temporal uses the SystemTime, and other parts of the engine (e.g. futexes, VM trace, profiling) use the standard library.

Proposal

This document proposes new types for defining engine-specific instants (JsInstant) and durations (JsDuration) internally.

Scope

These new types should not be used in JavaScript directly. The Date type and Temporal libraries would rely on these new types to build internal representations that can be used in JavaScript.

Technical Design

Instant

An instant inside the Boa engine is represented by the type JsInstant. This type can be constructed by using a builtins::date::Date, a std::time::SystemTime where available, or mocked in tests.

This type must at least have the following properties:

1. Monotonicity, ie. calling Instant multiple times in a single thread must always be equal or increase.
2. Convertible to the number of nanoseconds since EPOCH. This is necessary to allow conversion to JavaScript dates and times, notably with Temporal types.
3. Convertible to and from system time. The default implementation should use the system time.

The basic definition of this type would look like:

pub struct JsInstant { secs: i64, nsecs: u32 };

// Host provides a Clock implementation.
pub trait Clock {
  fn now(&self, context: &mut Context): JsInstant;
}

// Host provides a separate clock from host hooks.
impl ContextBuilder {
  pub fn clock<C: Clock + 'static>(mut self, clock: Rc<C>) -> Self { /* ... */ }
}

// The clock is part of the Realm.
impl Realm {
  pub fn clock(&self) -> Rc<dyn Clock> { /* ... */ }
}

// The context creates instants.
impl Context {
  pub fn instant(&mut self) -> JsInstant { self.realm().clock().now(self) }
}

Duration

A duration is defined as the difference of two instants and is represented by the type JsDuration. This is similar to the std::time::Duration type.

A duration is created by a JsInstant.

The basic definition of this type would look like:

pub struct JsDuration(u64);

Tasks

• Write preliminary design
• Write PR (and link)
• Gather feedback