feat(localdb): hybrid logical clock (UTC-ms<<16 | counter)

2026-07-17 20:58:02 -04:00
parent 61e5564c26
commit cf58077398
2 changed files with 123 additions and 0 deletions
@@ -0,0 +1,33 @@
+namespace ZB.MOM.WW.LocalDb.Hlc;
+
+/// <summary>64-bit HLC: (UTC unix-ms &lt;&lt; 16) | 16-bit logical counter. Thread-safe.</summary>
+public sealed class HybridLogicalClock
+{
+    private readonly Func<long> _utcNowMs;
+    private readonly Lock _lock = new();
+    private long _last;
+
+    public HybridLogicalClock(long initialValue = 0, Func<long>? utcNowMs = null)
+    {
+        _utcNowMs = utcNowMs ?? (() => DateTimeOffset.UtcNow.ToUnixTimeMilliseconds());
+        _last = initialValue;
+    }
+
+    public long Next()
+    {
+        lock (_lock)
+        {
+            var candidate = _utcNowMs() << 16;
+            _last = candidate > _last ? candidate : _last + 1; // +1 rolls counter; overflow naturally carries into physical bits
+            return _last;
+        }
+    }
+
+    /// <summary>Merge a peer's HLC so our next stamp orders after everything we've seen.</summary>
+    public void Observe(long remote) { lock (_lock) { if (remote > _last) _last = remote; } }
+
+    public long Current { get { lock (_lock) return _last; } }
+
+    public static long PhysicalMs(long hlc) => hlc >> 16;
+    public static int Counter(long hlc) => (int)(hlc & 0xFFFF);
+}