tickets

16.2 KB

1. // hl:time plugin — native shared library (libtime.so, dlopen'd by the runtime)
2. //
3. // The clock (D22):
4. // hl_time_now() → epoch milliseconds, UTC wall clock (Number)
5. // hl_time_timestamp(ms?) → ISO-8601 UTC "YYYY-MM-DDTHH:MM:SS.mmmZ" (String)
6. // hl_time_monotonic() → nanoseconds off a monotonic counter (Number)
7. //
8. // …and TIME AS AN EVENT SOURCE (mission 254):
9. // hl_time_timer(secs, repeat) → { id, events } — `events` is a LOOP SOURCE
10. // whose wake fd IS a timerfd, so the interpreter
11. // loop's epoll (mission 256) blocks on the
12. // kernel timer itself instead of polling
13. // hl_time_timer_stop(id) → disarm, close, retire
14. // hl_time_sleep(secs) → BLOCKING nanosleep (the creator's ruling: a
15. // basic tool for tests and debugging)
16. //
17. // The clock calls allocate nothing and hold no state; `timestamp` renders into a
18. // module-level buffer: the runtime dupes returned strings into its own tracker
19. // the instant the call returns (plugin_loader.zig hlToValue .hl_string) and a
20. // plugin call never yields, so the buffer cannot be observed stale or torn.
21. //
22. // Number is f64. Epoch ms (~1.8e12) is exact well past the year 200000, and
23. // monotonic ns stays exact for the first ~104 days of counter uptime (2^53 ns);
24. // beyond that the granularity coarsens above 1 ns, which is irrelevant for the
25. // difference-measurement the call exists for.
27. const std = @import("std");
28. const linux = std.os.linux;
29. const api = @import("plugin_api");
30. const HlValue = api.HlValue;
31. const HlObject = api.HlObject;
32. const HlField = api.HlField;
33. const HlIterator = api.HlIterator;
34. const HlString = api.HlString;
36. var gpa = std.heap.DebugAllocator(.{ .stack_trace_frames = 0 }){};
37. const allocator = gpa.allocator();
39. fn hlStr(s: []const u8) HlString {
40. return .{ .ptr = s.ptr, .len = s.len };
41. }
43. fn nowMs() i64 {
44. var ts: linux.timespec = undefined;
45. _ = linux.clock_gettime(linux.CLOCK.REALTIME, &ts);
46. return @as(i64, ts.sec) * 1000 + @divTrunc(@as(i64, ts.nsec), 1_000_000);
47. }
49. export fn hl_time_now(_: u32, _: [*]const HlValue) callconv(.c) HlValue {
50. return api.makeNumber(@floatFromInt(nowMs()));
51. }
53. export fn hl_time_monotonic(_: u32, _: [*]const HlValue) callconv(.c) HlValue {
54. var ts: linux.timespec = undefined;
55. _ = linux.clock_gettime(linux.CLOCK.MONOTONIC, &ts);
56. const ns: i64 = @as(i64, ts.sec) * 1_000_000_000 + @as(i64, ts.nsec);
57. return api.makeNumber(@floatFromInt(ns));
58. }
60. // "YYYY-MM-DDTHH:MM:SS.mmmZ" is 24 bytes; the year field widens for absurd
61. // inputs, so give it room rather than truncating.
62. var iso_buf: [40]u8 = undefined;
64. export fn hl_time_timestamp(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
65. // Argument is optional: absent, null, or non-numeric all mean "now". The
66. // .hl wrapper declares `timestamp(ms)`, so a no-arg call arrives as one
67. // hl_null — the same thing.
68. var ms: i64 = if (argc > 0 and argv[0].type == .hl_number)
69. @intFromFloat(argv[0].data.number)
70. else
71. nowMs();
73. // Pre-epoch instants: floor the division so the millisecond part stays in
74. // [0, 999] and the second walks backwards (std.time.epoch is u64-only).
75. var secs: i64 = @divFloor(ms, 1000);
76. var millis: i64 = ms - secs * 1000;
77. if (secs < 0) {
78. // Dates before 1970 have no u64 epoch representation; rather than
79. // render garbage, clamp to the epoch itself and say so via the value.
80. secs = 0;
81. millis = 0;
82. ms = 0;
83. }
85. const es = std.time.epoch.EpochSeconds{ .secs = @intCast(secs) };
86. const yd = es.getEpochDay().calculateYearDay();
87. const md = yd.calculateMonthDay();
88. const ds = es.getDaySeconds();
90. const out = std.fmt.bufPrint(&iso_buf, "{d:0>4}-{d:0>2}-{d:0>2}T{d:0>2}:{d:0>2}:{d:0>2}.{d:0>3}Z", .{
91. yd.year,
92. md.month.numeric(),
93. @as(u32, md.day_index) + 1,
94. ds.getHoursIntoDay(),
95. ds.getMinutesIntoHour(),
96. ds.getSecondsIntoMinute(),
97. @as(u32, @intCast(millis)),
98. }) catch return api.makeError("hl:time timestamp() could not format the instant");
100. return api.makeString(out);
101. }
103. // ═══════════════════════════════════════════════════════════════════════════
104. // TIME AS AN EVENT SOURCE (mission 254)
105. // ═══════════════════════════════════════════════════════════════════════════
106. //
107. // `every(n)` / `after(n)` / `until(t)` are ONE primitive: a timerfd registered
108. // with the interpreter's event loop as an ordinary source, exactly the shape
109. // `spawn()` hands back from hl:proc. Two properties are the whole reason it is a
110. // timerfd rather than a thread or a deadline the loop checks:
111. //
112. // THE WAKE FD IS THE TIMER ITSELF. Mission 256 taught the loop to block in one
113. // `epoll_wait` over its sources' `HlIterator.wake_fd`s. A timerfd IS such an
114. // fd, so a timer costs one kernel wakeup at the instant it is due — not a 1ms
115. // poll that could never resolve a 1ms interval in the first place. An idle
116. // process with no timers is untouched (`tools/idle-cpu-gate.sh`).
117. //
118. // THE KERNEL OWNS THE SCHEDULE, so `every` cannot drift. `timerfd_settime` is
119. // given an ABSOLUTE deadline on CLOCK_MONOTONIC plus an interval, and the
120. // kernel re-arms from the previous EXPIRY, never from when anyone read the fd.
121. // The handler's own runtime is therefore not added to the next round — which
122. // is exactly the defect a `sleep(interval)` loop has.
123. //
124. // WHY `tryNext` READS THE CLOCK AND NOT THE FD. `loop_wait.Waiter` DRAINS every
125. // fd it was woken by (`read(fd, &sink, 8)`) before the loop's poll round — that
126. // is the level-triggered race argument in loop_wait.zig's header, and it means
127. // the timerfd's expiration COUNT is already gone by the time this poll runs. So
128. // the count is not the signal; the deadline is. Both sides read the same
129. // CLOCK_MONOTONIC and the kernel expires at-or-after the absolute deadline it
130. // was handed, so `now >= deadline` is guaranteed true when the bell rings. A
131. // dropped or duplicated wake is harmless in both directions: a duplicate polls
132. // to `null`, and a missed one is picked up by the loop's 250ms safety timeout.
134. // RAW SYSCALLS, NO LIBC. This .so has never linked libc (`timestamp` renders
135. // with std.fmt and the clock reads go through `linux.clock_gettime`), and the
136. // timer half keeps it that way — `std.os.linux` has timerfd and nanosleep, so
137. // nothing here needs `build.zig` to gain a `link_libc` it did not have.
138. fn timerfdCreate() i32 {
139. const rc = linux.timerfd_create(.MONOTONIC, .{ .NONBLOCK = true, .CLOEXEC = true });
140. const fd: isize = @bitCast(rc);
141. return if (fd < 0) -1 else @intCast(fd);
142. }
144. fn timerfdSetAbs(fd: i32, spec: *const linux.itimerspec) bool {
145. const rc = linux.timerfd_settime(fd, .{ .ABSTIME = true }, spec, null);
146. return @as(isize, @bitCast(rc)) == 0;
147. }
149. fn timerfdDisarm(fd: i32) void {
150. const zero = linux.itimerspec{
151. .it_interval = .{ .sec = 0, .nsec = 0 },
152. .it_value = .{ .sec = 0, .nsec = 0 },
153. };
154. _ = linux.timerfd_settime(fd, .{}, &zero, null);
155. }
157. fn monoNs() i64 {
158. var ts: linux.timespec = undefined;
159. _ = linux.clock_gettime(linux.CLOCK.MONOTONIC, &ts);
160. return @as(i64, ts.sec) * 1_000_000_000 + @as(i64, ts.nsec);
161. }
163. /// THE FLOOR, and it is the SAME NUMBER IN BOTH REALMS (mission 254).
164. ///
165. /// The creator confirmed fractional seconds — "a millisecond is just 0.001 then
166. /// thats okay" — and server-side that is not the limit: a timerfd carries
167. /// nanoseconds and the loop blocks on it. THE BROWSER IS THE LIMIT, and it was
168. /// MEASURED rather than quoted (tests/browser/tests/66-timers.mjs prints the
169. /// number it measured on every run). HTML's timer nesting rule clamps a chained
170. /// `setTimeout(…, 0)` to 4ms from the fifth nesting level on, and a `setInterval`
171. /// asked for 1ms delivers ~4ms periods.
172. ///
173. /// So `every(0.001)` would mean two different things in the two realms, and the
174. /// SAME `on t.tick()` handler is meant to run in both. The brief's choice was
175. /// "document the divergence with the measured number, or clamp both realms to
176. /// the same honest minimum" — CLAMPED, because a silent target divergence is
177. /// already a named defect class in this tree and because a number the author
178. /// writes should mean one thing everywhere. Anything below the floor is raised
179. /// to it, in both realms (`server.js` carries the same constant), and
180. /// `plugins/time/server.hl` says so where an author will read it.
181. const FLOOR_NS: i64 = 4_000_000;
183. /// ONE ARMED TIMER. Never freed: the struct is ~48 bytes, it is referenced by an
184. /// iterator the runtime owns, and freeing it would need the loop's poll round and
185. /// the GC sweep to agree on an order they have no reason to. `stop()` closes the
186. /// fd (which is the only scarce resource) and marks it dead; the poll then answers
187. /// `null` forever, which is what a retired source must do.
188. const Timer = struct {
189. fd: i32 = -1,
190. /// 0 = ONE-SHOT. `after()` and `until()` are `every()` that fires once.
191. interval_ns: i64 = 0,
192. /// The next fire's ABSOLUTE CLOCK_MONOTONIC instant — the same value the
193. /// kernel holds, which is what makes `now >= deadline` exact rather than
194. /// approximate.
195. deadline_ns: i64 = 0,
196. count: f64 = 0,
197. stopped: bool = false,
198. };
200. /// id → Timer, 1-based; `0` is "no timer" so a default-initialised member is
201. /// never mistaken for one. Ids are never reused: `stop()` leaves the slot dead
202. /// rather than freeing it, so a stale id can only ever answer "already stopped".
203. var timers = std.ArrayListUnmanaged(*Timer).empty;
205. fn timerById(id: f64) ?*Timer {
206. if (id < 1) return null;
207. const idx: usize = @intFromFloat(id - 1);
208. if (idx >= timers.items.len) return null;
209. return timers.items[idx];
210. }
212. fn timerTryNext(ctx: ?*anyopaque) callconv(.c) HlValue {
213. const t: *Timer = @ptrCast(@alignCast(ctx orelse return api.makeNull()));
214. if (t.stopped) return api.makeNull();
215. const now = monoNs();
216. if (now < t.deadline_ns) return api.makeNull();
218. t.count += 1;
219. if (t.interval_ns == 0) {
220. // A ONE-SHOT IS SPENT. The .hl half retires the source and closes the fd
221. // (mission 249: a source that will never speak again must not keep the
222. // program alive); this flag makes the polls between here and there
223. // answer null rather than fire a second time.
224. t.stopped = true;
225. } else {
226. // SCHEDULED FROM THE ORIGIN, and CAUGHT UP BY SKIPPING. Advancing by one
227. // interval keeps the phase the first fire established, so the handler's
228. // own runtime never accumulates. If the loop was busy for longer than an
229. // interval the missed rounds are DROPPED rather than delivered as a
230. // burst — a periodic timer that owes you a backlog is a stampede, and
231. // the kernel's own timerfd overrun count is discarded for the same
232. // reason (see the header: the Waiter has already drained it).
233. t.deadline_ns += t.interval_ns;
234. while (t.deadline_ns <= now) t.deadline_ns += t.interval_ns;
235. }
237. const fields = allocator.alloc(HlField, 2) catch return api.makeNull();
238. fields[0] = .{ .key = hlStr("count"), .value = api.makeNumber(t.count) };
239. fields[1] = .{ .key = hlStr("at"), .value = api.makeNumber(@floatFromInt(nowMs())) };
240. const obj = allocator.create(HlObject) catch return api.makeNull();
241. obj.* = .{ .fields = fields.ptr, .field_count = 2, .deinit_fn = null };
242. return api.makeObject(obj);
243. }
245. fn timerDeinit(ctx: ?*anyopaque) callconv(.c) void {
246. const t: *Timer = @ptrCast(@alignCast(ctx orelse return));
247. t.stopped = true;
248. }
250. /// hl_time_timer(seconds, repeat) → { id, events }
251. export fn hl_time_timer(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
252. if (argc < 1 or argv[0].type != .hl_number) {
253. return api.makeError("hl:time timer: pass the interval in SECONDS (fractions allowed)");
254. }
255. const secs = argv[0].data.number;
256. if (!(secs == secs) or secs < 0) { // NaN or negative
257. return api.makeError("hl:time timer: the interval must be a positive number of seconds");
258. }
259. const repeat = argc >= 2 and argv[1].type == .hl_bool and argv[1].data.boolean;
261. var ns: i64 = @intFromFloat(secs * 1_000_000_000.0);
262. if (ns < FLOOR_NS) ns = FLOOR_NS;
264. const fd = timerfdCreate();
265. if (fd < 0) return api.makeError("hl:time timer: timerfd_create failed");
267. const t = allocator.create(Timer) catch return api.makeError("hl:time: out of memory");
268. t.* = .{ .fd = fd, .interval_ns = if (repeat) ns else 0, .deadline_ns = monoNs() + ns };
270. // ABSOLUTE, so the kernel and this plugin hold the SAME instant — the whole
271. // exactness argument in the header. The interval is the kernel's own re-arm,
272. // which is what makes `every` drift-free rather than nearly drift-free.
273. const spec = linux.itimerspec{
274. .it_interval = .{
275. .sec = if (repeat) @intCast(@divTrunc(ns, 1_000_000_000)) else 0,
276. .nsec = if (repeat) @intCast(@mod(ns, 1_000_000_000)) else 0,
277. },
278. .it_value = .{
279. .sec = @intCast(@divTrunc(t.deadline_ns, 1_000_000_000)),
280. .nsec = @intCast(@mod(t.deadline_ns, 1_000_000_000)),
281. },
282. };
283. if (!timerfdSetAbs(fd, &spec)) {
284. _ = linux.close(fd);
285. return api.makeError("hl:time timer: timerfd_settime failed");
286. }
288. timers.append(allocator, t) catch return api.makeError("hl:time: out of memory");
289. const id: f64 = @floatFromInt(timers.items.len);
291. const iter = allocator.create(HlIterator) catch return api.makeError("hl:time: out of memory");
292. iter.* = .{
293. .context = @ptrCast(t),
294. .next_fn = &timerTryNext,
295. .deinit_fn = &timerDeinit,
296. .try_next_fn = &timerTryNext,
297. .wake_fd = fd,
298. };
300. const fields = allocator.alloc(HlField, 2) catch return api.makeNull();
301. fields[0] = .{ .key = hlStr("id"), .value = api.makeNumber(id) };
302. fields[1] = .{ .key = hlStr("events"), .value = api.makeIterator(iter) };
303. const obj = allocator.create(HlObject) catch return api.makeNull();
304. obj.* = .{ .fields = fields.ptr, .field_count = 2, .deinit_fn = null };
305. return api.makeObject(obj);
306. }
308. /// hl_time_timer_stop(id) — disarm and close. TRUE when this call was the one
309. /// that stopped it. The caller retires the event source FIRST (Timer.hl), so the
310. /// loop has already dropped this fd from its epoll set by the time it is closed.
311. export fn hl_time_timer_stop(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
312. if (argc < 1 or argv[0].type != .hl_number) {
313. return api.makeError("hl:time timer stop: pass the id timer() returned");
314. }
315. const t = timerById(argv[0].data.number) orelse return api.makeBool(false);
316. const was_open = t.fd >= 0;
317. t.stopped = true;
318. if (t.fd >= 0) {
319. timerfdDisarm(t.fd);
320. _ = linux.close(t.fd);
321. t.fd = -1;
322. }
323. return api.makeBool(was_open);
324. }
326. /// hl_time_sleep(seconds) — BLOCKING, and that is the creator's ruling, not an
327. /// omission: *"sleep you need mostly for testing or debugging stuff, its what i
328. /// consider basic tools"*. It stops this thread, which inside a request handler
329. /// means the loop is stopped too; `after()` is the thing to use there, and
330. /// server.hl says so where an author will read it.
331. export fn hl_time_sleep(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
332. if (argc < 1 or argv[0].type != .hl_number) {
333. return api.makeError("hl:time sleep: pass the duration in SECONDS (fractions allowed)");
334. }
335. const secs = argv[0].data.number;
336. if (!(secs == secs) or secs <= 0) return api.makeBool(false);
337. const ns: i64 = @intFromFloat(secs * 1_000_000_000.0);
338. // EINTR leaves the remainder; a signal must not silently shorten the sleep.
339. var req = linux.timespec{ .sec = @intCast(@divTrunc(ns, 1_000_000_000)), .nsec = @intCast(@mod(ns, 1_000_000_000)) };
340. var rem = linux.timespec{ .sec = 0, .nsec = 0 };
341. while (@as(isize, @bitCast(linux.nanosleep(&req, &rem))) != 0) {
342. if (rem.sec == 0 and rem.nsec == 0) break;
343. req = rem;
344. rem = .{ .sec = 0, .nsec = 0 };
345. }
346. return api.makeBool(true);
347. }