notes

8.2 KB

1. // hl:time — the clock AND time as an event source. JS twin of
2. // plugins/time/time.zig, and the one file BOTH other realms run: the JavaScript
3. // transpiler target copies it into `hl-modules/time.js`, and hl:web serves it to
4. // the BROWSER as `hl-time.js` (hl:time declares no `"realm": "server"`, so a
5. // client handler may reach it — plugins/web/web_framework.hl `packagePaths`).
6. //
7. // Parity contract with the native plugin:
8. // now() → epoch milliseconds, integer-valued
9. // timestamp(ms?) → "YYYY-MM-DDTHH:MM:SS.mmmZ", exactly 24 chars, UTC.
10. // No argument (or a non-number) means "now"; an epoch-ms
11. // argument renders THAT instant, which is what makes the
12. // call testable — timestamp(0) is always the epoch.
13. // monotonic() → nanoseconds off a monotonic counter. Origin arbitrary;
14. // only differences are meaningful.
15. // every(s) → a repeating Timer; `on t.tick()` until `t.stop()`
16. // after(s) → a one-shot Timer, `s` seconds from now
17. // until(epochMs) → a one-shot Timer at that instant
18. // sleep(s) → BLOCKING. Yes, in a browser too — see below.
20. export function now() { return Date.now(); }
22. export function timestamp(ms) {
23. // Date#toISOString already emits exactly the native format for in-range
24. // instants. Pre-epoch values are clamped the same way the native plugin
25. // clamps them (std.time.epoch is u64-only, so 1970 is the floor on both
26. // sides and the two targets must agree on what happens below it).
27. let t = typeof ms === 'number' && Number.isFinite(ms) ? Math.trunc(ms) : Date.now();
28. if (t < 0) t = 0;
29. return new Date(t).toISOString();
30. }
32. export function monotonic() {
33. // process.hrtime.bigint() is Node's CLOCK_MONOTONIC. Converted to a plain
34. // Number because Hybriel has no bigint; same f64 caveat as the native side
35. // (exact for the first ~104 days of counter uptime).
36. if (typeof process !== 'undefined' && process.hrtime && process.hrtime.bigint) {
37. return Number(process.hrtime.bigint());
38. }
39. // Browser/other host fallback: performance.now() is ms with sub-ms
40. // resolution off a monotonic origin.
41. return Math.round(performance.now() * 1e6);
42. }
44. // ═══════════════════════════════════════════════════════════════════════════
45. // TIME AS AN EVENT SOURCE (mission 254)
46. // ═══════════════════════════════════════════════════════════════════════════
47. //
48. // THE FLOOR IS THE SAME NUMBER AS THE NATIVE PLUGIN'S, and this is the realm
49. // that sets it. Server-side a timerfd carries nanoseconds and the event loop
50. // blocks on it, so there is no floor there at all; the browser has one, and it
51. // was MEASURED rather than quoted from the spec — tests/browser/tests/66-timers.mjs
52. // drives a real page and prints the number it measured on every run. HTML's
53. // timer nesting rule clamps a chained `setTimeout(…, 0)` to 4ms from the fifth
54. // nesting level, and a `setInterval` asked for 1ms delivers ~4ms periods.
55. //
56. // The same `on t.tick()` handler is meant to run in both realms, so `every(0.001)`
57. // must not mean two different things depending on where it ran: both sides raise
58. // anything below the floor to it. (plugins/time/time.zig FLOOR_NS = 4_000_000.)
59. export const TIMER_FLOOR_SECONDS = 0.004;
61. /** Monotonic milliseconds, fractional. `performance` is a global in Node ≥16 and
62. * in every browser; `Date.now()` is the last-resort fallback and is not
63. * monotonic, which only costs accuracy across a clock adjustment. */
64. function monoMs() {
65. if (typeof performance !== 'undefined' && performance.now) return performance.now();
66. return Date.now();
67. }
69. /** ONE ARMED TIMER — the twin of plugins/time/Timer.hl.
70. *
71. * `on t.tick()` reaches this through `__hlOn`, which is the ONE registration
72. * protocol both JS realms use: the transpiler target's `hlScopedBus`
73. * (js/src/runtime/runtime.js) and hl:web's client runtime (hl-core.js
74. * `__hlBindSources`) each end up calling it with the event name and a handler.
75. * A plugin object is not an hl class instance and has no `constructor.__events__`,
76. * so it could not otherwise be the target of an instance-scoped handler.
77. *
78. * SCHEDULED FROM THE ORIGIN, like the native half: each round's delay is
79. * computed against `origin + n × period`, never `period` from where the last
80. * handler finished, so the handler's own runtime does not accumulate. A round
81. * the host was too busy to deliver is SKIPPED rather than queued — a periodic
82. * timer that owes you a backlog is a stampede.
83. *
84. * A CHAINED `setTimeout` RATHER THAN `setInterval`, for the same reason: the
85. * chain lets each delay be recomputed from the origin, and `setInterval`'s
86. * behaviour when a callback overruns its period differs between hosts. */
87. class HlTimer {
88. constructor(seconds, repeating) {
89. this.seconds = Math.max(TIMER_FLOOR_SECONDS, Number(seconds) || 0);
90. this.repeating = !!repeating;
91. this.running = true;
92. this.count = 0;
93. this.__handlers = new Map();
94. this.__origin = monoMs();
95. this.__n = 0;
96. this.__h = null;
97. this.__arm();
98. }
100. __arm() {
101. const period = this.seconds * 1000;
102. this.__n += 1;
103. const due = this.__origin + this.__n * period;
104. this.__h = setTimeout(() => this.__fire(), Math.max(0, due - monoMs()));
105. }
107. __fire() {
108. this.__h = null;
109. if (!this.running) return;
110. this.count += 1;
111. const ev = { count: this.count, at: Date.now() };
112. if (this.repeating) {
113. // skip whatever the host was too busy to deliver, keeping the phase
114. const period = this.seconds * 1000;
115. const now = monoMs();
116. while (this.__origin + this.__n * period <= now) this.__n += 1;
117. this.__n -= 1;
118. this.__arm();
119. } else {
120. // A SPENT ONE-SHOT RETIRES ITSELF before the tick is delivered — the
121. // same rule as the native half (mission 249: a source that will never
122. // speak again must not keep the program alive; in Node that is
123. // literally true, an un-cleared timer keeps the process running).
124. this.running = false;
125. }
126. const list = this.__handlers.get('tick');
127. if (list) for (const fn of list.slice()) fn(ev);
128. }
130. /** The registration protocol — see the class comment. */
131. __hlOn(event, fn) {
132. let list = this.__handlers.get(event);
133. if (!list) { list = []; this.__handlers.set(event, list); }
134. list.push(fn);
135. return this;
136. }
138. /** Stop an interval. True when this call was the one that stopped it. */
139. stop() {
140. if (!this.running) return false;
141. this.running = false;
142. if (this.__h !== null) { clearTimeout(this.__h); this.__h = null; }
143. return true;
144. }
145. }
147. /** A REPEATING timer: `on t.tick()` fires every `seconds` until `t.stop()`. */
148. export function every(seconds) { return new HlTimer(seconds, true); }
150. /** A ONE-SHOT: `on t.tick()` fires once, `seconds` from now, and retires. */
151. export function after(seconds) { return new HlTimer(seconds, false); }
153. /** A ONE-SHOT AT AN INSTANT. `epochMs` is what `now()` answers; an instant
154. * already past fires immediately (at the floor). */
155. export function until(epochMs) {
156. const delay = (Number(epochMs) - Date.now()) / 1000;
157. return new HlTimer(delay > 0 ? delay : 0, false);
158. }
160. /** BLOCK for `seconds`. The creator's ruling: a basic tool for tests and
161. * debugging, and it blocks — inside a server, `after()` is the thing to use.
162. *
163. * `Atomics.wait` is the only real block JavaScript has, and it is FORBIDDEN on
164. * a browser's main thread (it throws TypeError). So the browser gets a spin on
165. * the monotonic clock instead, which is the same observable behaviour — the tab
166. * is frozen for the duration — reached a different way. That is what a blocking
167. * sleep IS; the docs say so beside it rather than pretending otherwise. */
168. export function sleep(seconds) {
169. const ms = Number(seconds) * 1000;
170. if (!(ms > 0)) return false;
171. try {
172. if (typeof SharedArrayBuffer !== 'undefined' && typeof Atomics !== 'undefined') {
173. Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
174. return true;
175. }
176. } catch { /* main thread — fall through to the spin */ }
177. const until_ = monoMs() + ms;
178. while (monoMs() < until_) { /* the block */ }
179. return true;
180. }