tickets

6.6 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.
7. TIME ZONES are five more (ticket #5): `offset`, `local`, `fromLocal`,
8. `localTimestamp` and `isZone`, over the system's IANA database natively and
9. Intl in the browser, with identical answers. README.md has the rules — the
10. DST gap and fold, the units, the error cases. Calendar arithmetic and
11. free-form formatting stay a userland concern.
13. TIME AS AN EVENT SOURCE is `every`, `after` and `until`. Each hands back a
14. `Timer` you subscribe the way you subscribe a spawned process:
16. let interval = every(360) \\ every six minutes, forever
17. on interval.tick(t) { … }
18. interval.stop() \\ …until you stop it
20. let timeout = after(6) \\ once, six seconds from now
21. on timeout.tick() { … } \\ and then the program can end
23. let deadline = until(t) \\ once, at that epoch-ms instant
24. on deadline.tick() { … }
26. SECONDS, EVERYWHERE, FRACTIONS ALLOWED. `every(0.25)` is four times a second
27. and `after(0.5)` is half a second. One unit for every duration in this
28. package, because mixing them is a defect this project has already had to
29. diagnose in someone else's code — a SECONDS-valued lifetime compared against
30. millisecond deltas turned a year into 8¾ hours. `now()` stays milliseconds
31. because it is an INSTANT, not a duration.
33. THE FLOOR IS 4 ms, IN BOTH REALMS, and it is measured rather than quoted.
34. Server-side a timerfd carries nanoseconds and the event loop blocks on it, so
35. there is no floor at all; the BROWSER has one — HTML clamps a nested
36. `setTimeout(…, 0)` to 4ms and a 1ms `setInterval` delivers ~4ms periods
37. (measured by `tests/browser/tests/66-timers.mjs`, which prints its number on
38. every run). The same `on t.tick()` handler is meant to run in both realms, so
39. a value below the floor is RAISED to it on both sides rather than meaning two
40. different things depending on where it ran.
42. ONE EVENT NAME. All three fire `tick` — see Timer.hl for why.
44. `until()` TAKES A TIMESTAMP, not a string. `until('23:30')` needs date
45. parsing with timezone and format rules, which is its own piece of work and
46. not part of the clock; write `until(someEpochMs)` and build the epoch-ms with
47. whatever calendar logic your app already has.
49. `sleep(n)` BLOCKS — that is what it is for. It is a basic tool for tests and
50. scripts, and it stops the whole thread: called inside a request handler, no
51. other request is served until it returns. Inside a server you want `after()`,
52. which stops nothing. *\
54. \* Wall clock, milliseconds since the Unix epoch (UTC). Integer-valued. *\
55. now() {
56. return __native("time.now")
57. }
59. \* ISO-8601 UTC string, always `YYYY-MM-DDTHH:MM:SS.mmmZ` (24 chars).
60. With no argument it renders `now()`. With an epoch-ms argument it renders
61. THAT instant — which is what makes it testable: `timestamp(0)` is always
62. "1970-01-01T00:00:00.000Z". *\
63. timestamp(ms) {
64. return __native("time.timestamp", ms)
65. }
67. \* The zone's offset from UTC at an instant, in SECONDS east of UTC (Vienna in
68. summer: 7200). DST included — it is the offset actually in force. *\
69. offset(
70. Number ms \\ the instant, in epoch milliseconds (what now() returns)
71. String zone \\ an IANA zone name, e.g. 'Europe/Vienna'
72. ) {
73. return __native("time.offset", ms, zone)
74. }
76. \* The wall-clock reading in a zone at an instant: { year, month (1-12), day,
77. hour, minute, second, millisecond, weekday (1 = Monday … 7 = Sunday),
78. offset (seconds east of UTC) }. *\
79. local(
80. Number ms \\ the instant, in epoch milliseconds
81. String zone \\ an IANA zone name
82. ) {
83. return __native("time.local", ms, zone)
84. }
86. \* The instant a wall-clock reading in a zone names, in epoch ms. `year` is
87. required; month and day default to 1, the rest to 0; values past their range
88. carry over (month 13 is next January). A reading in a DST FOLD answers the
89. EARLIER instant; one in a DST GAP is moved forward by the gap. *\
90. fromLocal(
91. Hybrid fields \\ { year, month, day, hour, minute, second, millisecond }
92. String zone \\ an IANA zone name
93. ) {
94. return __native("time.fromLocal", fields, zone)
95. }
97. \* ISO-8601 in a zone: `YYYY-MM-DDTHH:MM:SS.mmm+HH:MM`, the local reading and
98. the offset in force. `localTimestamp(0, 'Europe/Vienna')` is always
99. "1970-01-01T01:00:00.000+01:00". *\
100. localTimestamp(
101. Number ms \\ the instant, in epoch milliseconds
102. String zone \\ an IANA zone name
103. ) {
104. return __native("time.localTimestamp", ms, zone)
105. }
107. \* True when this realm's zone database knows the name (case-sensitive). *\
108. isZone(
109. String name \\ a candidate IANA zone name
110. ) {
111. return __native("time.isZone", name)
112. }
114. \* Monotonic counter in nanoseconds. Never goes backwards, unaffected by
115. clock adjustments; the origin is arbitrary, so only DIFFERENCES mean
116. anything. Use it to measure, never to timestamp. *\
117. monotonic() {
118. return __native("time.monotonic")
119. }
121. \* A REPEATING timer: `on t.tick()` fires every `seconds` until `t.stop()`, and
122. a program whose only source is an interval runs forever — that is the point.
123. Scheduled from the ORIGIN, not from each fire, so the handler's own runtime
124. never accumulates into the next round. *\
125. every(
126. Number seconds \\ the period, in seconds; fractions allowed, floor 0.004
127. ) {
128. return new Timer().start(seconds, true)
129. }
131. \* A ONE-SHOT: `on t.tick()` fires once, `seconds` from now, and the timer then
132. RETIRES ITS SOURCE — so a program whose only source was an `after()` ends
133. after it fires instead of hanging forever. *\
134. after(
135. Number seconds \\ the delay, in seconds; fractions allowed, floor 0.004
136. ) {
137. return new Timer().start(seconds, false)
138. }
140. \* A ONE-SHOT AT AN INSTANT: `until(t)` is `after((t - now()) / 1000)`. `t` is
141. epoch MILLISECONDS — the same thing `now()` answers and `timestamp(ms)`
142. renders — because that is this package's instant. An instant already past
143. fires immediately. *\
144. until(
145. Number epochMs \\ the instant, in epoch milliseconds (what now() returns)
146. ) {
147. let delay = (epochMs - __native("time.now")) / 1000
148. if (delay < 0) {
149. delay = 0
150. }
151. return new Timer().start(delay, false)
152. }
154. \* BLOCK this thread for `seconds`. The creator's ruling: a basic tool for tests
155. and debugging. It blocks the event loop too, so nothing else is served while
156. it runs — inside a server, use `after()`. Returns true when it slept. *\
157. sleep(
158. Number seconds \\ how long to block, in seconds; fractions allowed
159. ) {
160. return __native("time.sleep", seconds)
161. }