refactor: migrate to Zig 0.16.0-dev.2676 PriorityQueue API

- Rename PriorityQueue methods: init→initContext, add→push,
  remove→pop, removeIndex→popIndex, deinit now takes allocator
- Add self.* = undefined in EventClock.deinit for memory poisoning
- Split triple compound condition in SlotClock AdvanceIterator
- Update workaround comments for macOS GCD bug #31307

Author: GrapeBaBa

src/EventClock.zig

@@ -88,7 +88,7 @@ pub fn init(self: *EventClock, allocator: Allocator, config: Config, io_handle:
         .allocator = allocator,
         .io = io_handle,
         .clock = undefined,
-        .waiters = WaiterQueue.init(allocator, {}),
+        .waiters = WaiterQueue.initContext({}),
     };
     self.clock = SlotClock.init(config, TimeSource.fromIo(&self.io)) catch return error.InvalidConfig;
 }
@@ -106,8 +106,8 @@ pub fn stop(self: *EventClock) void {
     self.abortAllWaiters();
 }
 
-/// WORKAROUND for Zig bug #31307: always await, never cancel sleeping futures.
-/// See: https://codeberg.org/ziglang/zig/issues/31307
+/// Await loop fiber completion.  Uses `await` (not `cancel`) because
+/// `Future.cancel` segfaults on macOS GCD (Zig bug #31307).
 pub fn join(self: *EventClock) void {
     var maybe_future = self.loop_future;
     self.loop_future = null;
@@ -124,7 +124,8 @@ pub fn deinit(self: *EventClock) void {
     self.epoch_snapshot.deinit(self.allocator);
     self.slot_listeners.deinit(self.allocator);
     self.epoch_listeners.deinit(self.allocator);
-    self.waiters.deinit();
+    self.waiters.deinit(self.allocator);
+    self.* = undefined;
 }
 
 // ── Listener API ──
@@ -276,8 +277,8 @@ pub const WaitForSlotResult = struct {
 
     pub fn await(self: *WaitForSlotResult, io: std.Io) Error!void {
         const result = self.inner.await(io);
-        // Free AFTER await returns — workaround for Zig futex use-after-free
-        // where GCD still holds a reference to the event address after wake.
+        // Free AFTER await returns — the OS futex implementation may still
+        // reference the Event address briefly after wake.
         if (self.state) |s| s.allocator.destroy(s);
         self.state = null;
         return result;
@@ -310,7 +311,7 @@ pub fn waitForSlot(self: *EventClock, target: Slot) Error!WaitForSlotResult {
         self.allocator.destroy(state);
         return WaitForSlotResult.immediate(error.Aborted);
     }
-    self.waiters.add(.{ .target = target, .state = state }) catch return error.OutOfMemory;
+    self.waiters.push(self.allocator, .{ .target = target, .state = state }) catch return error.OutOfMemory;
     self.dispatchWaiters(self.clock.current_slot);
 
     return .{
@@ -329,15 +330,14 @@ pub fn cancelWait(self: *EventClock, result: *WaitForSlotResult) void {
         // won't dereference the freed state pointer.
         for (self.waiters.items, 0..) |entry, i| {
             if (entry.state == state) {
-                _ = self.waiters.removeIndex(i);
+                _ = self.waiters.popIndex(i);
                 break;
             }
         }
         state.aborted = true;
         state.event.set(state.io);
     }
-    // Must await the fiber so it finishes before we free its state.
-    // (Cannot use Future.cancel due to Zig bug #31307.)
+    // Await the fiber so it finishes before we free its state.
     // The fiber returns error.Aborted (expected) or {} (already dispatched).
     _ = result.inner.await(self.io) catch |err| {
         std.debug.assert(err == error.Aborted);
@@ -395,14 +395,14 @@ fn dispatchWaiters(self: *EventClock, current_slot: ?Slot) void {
     const slot = current_slot orelse return;
     while (self.waiters.peek()) |head| {
         if (head.target > slot) break;
-        const waiter = self.waiters.remove();
+        const waiter = self.waiters.pop().?;
         waiter.state.aborted = false;
         waiter.state.event.set(waiter.state.io);
     }
 }
 
 fn abortAllWaiters(self: *EventClock) void {
-    while (self.waiters.removeOrNull()) |waiter| {
+    while (self.waiters.pop()) |waiter| {
         waiter.state.aborted = true;
         waiter.state.event.set(waiter.state.io);
     }
@@ -438,19 +438,17 @@ fn runAutoLoop(self: *EventClock) void {
             break;
         };
         // Sleep in short chunks so we can check `stopped` promptly.
-        // Without this, join() must wait for the full sleep to finish
-        // (we use await, not cancel, due to Zig bug #31307).
+        // We use await (not cancel) in join() because Future.cancel
+        // segfaults on macOS GCD (Zig bug #31307).
         const chunk_ms = @min(next_ms, 500);
         const sleep_ms = std.math.cast(i64, @max(@as(u64, 1), chunk_ms)) orelse std.math.maxInt(i64);
 
-        // Sleep failure (e.g., I/O shutdown, interrupt) is transient — safe to
-        // retry from the top of the loop, which will re-check `stopped` first.
         std.Io.sleep(
             self.io,
             std.Io.Duration.fromMilliseconds(sleep_ms),
             .awake,
-        ) catch |err| {
-            std.log.debug("EventClock: sleep failed ({s}), retrying", .{@errorName(err)});
+        ) catch {
+            // Transient error — re-check stopped flag.
             continue;
         };
 
@@ -465,8 +463,8 @@ fn runAutoLoop(self: *EventClock) void {
 
 fn waitForSlotFutureAwait(state: *WaitState) Error!void {
     // NOTE: Do NOT free state here. The caller (WaitForSlotResult.await) frees
-    // it AFTER this future completes — workaround for Zig futex use-after-free
-    // where GCD still holds a reference to the event address after wake.
+    // it AFTER this future completes, ensuring the Event address remains valid
+    // until the futex wake is fully processed by the OS.
     state.event.waitUncancelable(state.io);
     if (state.aborted) return error.Aborted;
 }
@@ -808,7 +806,7 @@ test "real-time: multi-slot advancement delivers ordered events" {
     }
 }
 
-test "real-time: stop returns within chunk window" {
+test "real-time: stop+join returns within chunk window" {
     var rt: TestIo = undefined;
     try rt.init();
     defer rt.deinit();
@@ -824,16 +822,16 @@ test "real-time: stop returns within chunk window" {
 
     clock.start();
 
-    // Give the loop fiber time to enter its first sleep chunk.
+    // Give the loop fiber time to enter its sleep.
     std.Io.sleep(io_handle, std.Io.Duration.fromMilliseconds(50), .awake) catch {};
 
     const before_ms = nowMsAt(io_handle);
     clock.stop();
     clock.join();
     const elapsed = nowMsAt(io_handle) - before_ms;
 
-    // The 500ms chunking means join() should return within ~500ms + overhead,
-    // NOT after the full 12-second slot duration.
+    // The loop sleeps in 500ms chunks so it checks `stopped` promptly —
+    // well under the full 12-second slot duration.
     try testing.expect(elapsed < 1500);
 }
 

src/SlotClock.zig

@@ -52,8 +52,12 @@ pub const AdvanceIterator = struct {
         // Check epoch boundary — epochAtSlot returns ?Epoch
         const prev_epoch = slot_math.epochAtSlot(self.clock.config, cur);
         const new_epoch = slot_math.epochAtSlot(self.clock.config, next_slot);
-        if (prev_epoch != null and new_epoch != null and prev_epoch.? < new_epoch.?) {
-            self.pending_epoch = new_epoch.?;
+        if (prev_epoch) |prev_ep| {
+            if (new_epoch) |new_ep| {
+                if (prev_ep < new_ep) {
+                    self.pending_epoch = new_ep;
+                }
+            }
         }
 
         return .{ .slot = next_slot };