Interface IHybridLogicalClock

Namespace

DotCompute.Abstractions.Temporal

Assembly

DotCompute.Abstractions.dll

Provides Hybrid Logical Clock (HLC) functionality for distributed causality tracking across GPU kernels.

public interface IHybridLogicalClock

Remarks

HLC is essential for GPU-native actor systems and distributed kernel coordination because:

• Causal Message Ordering: Ensures messages are processed in happened-before order
• Conflict Detection: Identifies concurrent operations for conflict resolution
• Replay and Recovery: Provides deterministic ordering for checkpoint replay
• Distributed Debugging: Tracks causality across multiple kernels and GPUs

Thread Safety: All HLC operations are thread-safe using atomic operations. Multiple GPU threads can safely call Tick() and Update() concurrently without data races.

Performance:

• Tick(): ~20ns (1 atomic increment + 1 timestamp read)
• Update(): ~50ns (1 atomic max + 1 atomic increment + 1 timestamp read)

Integration with Timing API: HLC uses the existing GPU Timing API (ITimingProvider) for high-precision physical timestamps. This ensures nanosecond accuracy on supported hardware (CUDA CC 6.0+).

Methods

GetCurrent()

Gets the current HLC timestamp without advancing the clock.

HlcTimestamp GetCurrent()

Returns

HlcTimestamp

The current HLC timestamp.

Remarks

Used for reading the clock state without modifying it (e.g., for diagnostics).

Reset(HlcTimestamp)

Resets the clock to a specific timestamp (for testing or recovery).

void Reset(HlcTimestamp timestamp)

Parameters

timestamp HlcTimestamp

The timestamp to reset to.

Remarks

Caution: Resetting the clock can violate causality if not done carefully. Only use for testing, checkpoint recovery, or kernel restart scenarios.

TickAsync(CancellationToken)

Advances the clock for a local event and returns the new timestamp.

Task<HlcTimestamp> TickAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token for the async operation.

Returns

Task<HlcTimestamp>

A task representing the async operation, returning a new HLC timestamp.

Remarks

Operation:

pt_new = GetPhysicalTime()
if (pt_new > pt_old):
    logical = 0
else:
    logical = logical + 1
return (pt_new, logical)

Usage: Call Tick() before processing a local message or event.

Thread Safety: Safe to call from multiple threads concurrently.

UpdateAsync(HlcTimestamp, CancellationToken)

Updates the clock based on a received remote timestamp and returns the new local timestamp.

Task<HlcTimestamp> UpdateAsync(HlcTimestamp remoteTimestamp, CancellationToken cancellationToken = default)

Parameters

remoteTimestamp HlcTimestamp

The timestamp received from another kernel or actor.

cancellationToken CancellationToken

Cancellation token for the async operation.

Returns

Task<HlcTimestamp>

A task representing the async operation, returning a new HLC timestamp that preserves causality.

Remarks

Operation:

pt_new = GetPhysicalTime()
pt_max = max(pt_old, remote.PhysicalTime)

if (pt_new > pt_max):
    logical = 0
elif (pt_max == pt_old):
    logical = max(logical_old, remote.Logical) + 1
else:
    logical = remote.Logical + 1

return (max(pt_new, pt_max), logical)

Usage: Call UpdateAsync() after receiving a message from another kernel.

Thread Safety: Safe to call from multiple threads concurrently.