gitoria

4.7 KB

1. \* hl:time — the clock, and TIME AS AN EVENT SOURCE. Native realm wrapper (see
2. server.js for the twin the JavaScript target and the BROWSER both run).
4. THE CLOCK is three calls, deliberately: a wall clock you can store, a
5. human/interchange rendering of it, and a monotonic counter you can subtract.
6. Everything else (formatting, timezones, arithmetic) is a userland concern.
8. TIME AS AN EVENT SOURCE is `every`, `after` and `until`. Each hands back a
9. `Timer` you subscribe the way you subscribe a spawned process:
11. let interval = every(360) \\ every six minutes, forever
12. on interval.tick(t) { … }
13. interval.stop() \\ …until you stop it
15. let timeout = after(6) \\ once, six seconds from now
16. on timeout.tick() { … } \\ and then the program can end
18. let deadline = until(t) \\ once, at that epoch-ms instant
19. on deadline.tick() { … }
21. SECONDS, EVERYWHERE, FRACTIONS ALLOWED. `every(0.25)` is four times a second
22. and `after(0.5)` is half a second. One unit for every duration in this
23. package, because mixing them is a defect this project has already had to
24. diagnose in someone else's code — a SECONDS-valued lifetime compared against
25. millisecond deltas turned a year into 8¾ hours. `now()` stays milliseconds
26. because it is an INSTANT, not a duration.
28. THE FLOOR IS 4 ms, IN BOTH REALMS, and it is measured rather than quoted.
29. Server-side a timerfd carries nanoseconds and the event loop blocks on it, so
30. there is no floor at all; the BROWSER has one — HTML clamps a nested
31. `setTimeout(…, 0)` to 4ms and a 1ms `setInterval` delivers ~4ms periods
32. (measured by `tests/browser/tests/66-timers.mjs`, which prints its number on
33. every run). The same `on t.tick()` handler is meant to run in both realms, so
34. a value below the floor is RAISED to it on both sides rather than meaning two
35. different things depending on where it ran.
37. ONE EVENT NAME. All three fire `tick` — see Timer.hl for why.
39. `until()` TAKES A TIMESTAMP, not a string. `until('23:30')` needs date
40. parsing with timezone and format rules, which is its own piece of work and
41. not part of the clock; write `until(someEpochMs)` and build the epoch-ms with
42. whatever calendar logic your app already has.
44. `sleep(n)` BLOCKS — that is what it is for. It is a basic tool for tests and
45. scripts, and it stops the whole thread: called inside a request handler, no
46. other request is served until it returns. Inside a server you want `after()`,
47. which stops nothing. *\
49. \* Wall clock, milliseconds since the Unix epoch (UTC). Integer-valued. *\
50. now() {
51. return __native("time.now")
52. }
54. \* ISO-8601 UTC string, always `YYYY-MM-DDTHH:MM:SS.mmmZ` (24 chars).
55. With no argument it renders `now()`. With an epoch-ms argument it renders
56. THAT instant — which is what makes it testable: `timestamp(0)` is always
57. "1970-01-01T00:00:00.000Z". *\
58. timestamp(ms) {
59. return __native("time.timestamp", ms)
60. }
62. \* Monotonic counter in nanoseconds. Never goes backwards, unaffected by
63. clock adjustments; the origin is arbitrary, so only DIFFERENCES mean
64. anything. Use it to measure, never to timestamp. *\
65. monotonic() {
66. return __native("time.monotonic")
67. }
69. \* A REPEATING timer: `on t.tick()` fires every `seconds` until `t.stop()`, and
70. a program whose only source is an interval runs forever — that is the point.
71. Scheduled from the ORIGIN, not from each fire, so the handler's own runtime
72. never accumulates into the next round. *\
73. every(
74. Number seconds \\ the period, in seconds; fractions allowed, floor 0.004
75. ) {
76. return new Timer().start(seconds, true)
77. }
79. \* A ONE-SHOT: `on t.tick()` fires once, `seconds` from now, and the timer then
80. RETIRES ITS SOURCE — so a program whose only source was an `after()` ends
81. after it fires instead of hanging forever. *\
82. after(
83. Number seconds \\ the delay, in seconds; fractions allowed, floor 0.004
84. ) {
85. return new Timer().start(seconds, false)
86. }
88. \* A ONE-SHOT AT AN INSTANT: `until(t)` is `after((t - now()) / 1000)`. `t` is
89. epoch MILLISECONDS — the same thing `now()` answers and `timestamp(ms)`
90. renders — because that is this package's instant. An instant already past
91. fires immediately. *\
92. until(
93. Number epochMs \\ the instant, in epoch milliseconds (what now() returns)
94. ) {
95. let delay = (epochMs - __native("time.now")) / 1000
96. if (delay < 0) {
97. delay = 0
98. }
99. return new Timer().start(delay, false)
100. }
102. \* BLOCK this thread for `seconds`. The creator's ruling: a basic tool for tests
103. and debugging. It blocks the event loop too, so nothing else is served while
104. it runs — inside a server, use `after()`. Returns true when it slept. *\
105. sleep(
106. Number seconds \\ how long to block, in seconds; fractions allowed
107. ) {
108. return __native("time.sleep", seconds)
109. }