Struct HlcTimestamp

Namespace

DotCompute.Abstractions.Temporal

Assembly

DotCompute.Abstractions.dll

Represents a Hybrid Logical Clock (HLC) timestamp for distributed causality tracking.

public readonly struct HlcTimestamp : IEquatable<HlcTimestamp>, IComparable<HlcTimestamp>

Implements

IEquatable<HlcTimestamp>

IComparable<HlcTimestamp>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Remarks

HLC combines physical time (wall-clock) with logical time (Lamport counter) to provide:

• Causality Tracking: Preserves happened-before relationships
• Total Ordering: Provides consistent ordering across distributed kernels
• Physical Proximity: Timestamps close in physical time

HLC Structure:

timestamp = (physical_time, logical_counter)
physical_time: 64-bit nanoseconds since epoch
logical_counter: 32-bit Lamport counter

Comparison Rules:

(pt1, l1) < (pt2, l2) if:
  - pt1 < pt2, OR
  - pt1 == pt2 AND l1 < l2

Example Usage:

// Create HLC for this kernel
var hlc = accelerator.CreateHybridLogicalClock();

// Local event: advance clock
var timestamp1 = hlc.Tick();

// Receive message with remote timestamp
var remoteTimestamp = receiveMessage();
var timestamp2 = hlc.Update(remoteTimestamp);

// Compare timestamps for causality
if (timestamp1.HappenedBefore(timestamp2))
{
    // timestamp1 causally precedes timestamp2
}

Properties

LogicalCounter

Gets the logical counter component for causality tracking.

public int LogicalCounter { get; init; }

Property Value

int

Lamport logical clock counter, incremented when:

• Local event occurs (Tick)
• Remote timestamp received with same physical time (Update)

PhysicalTimeNanos

Gets the physical time component in nanoseconds since epoch.

public long PhysicalTimeNanos { get; init; }

Property Value

long

Physical wall-clock time captured from the GPU or CPU timing provider. Resolution: 1ns on CUDA CC 6.0+ (globaltimer), 1μs on older GPUs (events).

Methods

CompareTo(HlcTimestamp)

Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.

public int CompareTo(HlcTimestamp other)

Parameters

other HlcTimestamp

An object to compare with this instance.

Returns

int

A value that indicates the relative order of the objects being compared. The return value has these meanings:

Value	Meaning
Less than zero	This instance precedes other in the sort order.
Zero	This instance occurs in the same position in the sort order as other.
Greater than zero	This instance follows other in the sort order.

Equals(HlcTimestamp)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(HlcTimestamp other)

Parameters

other HlcTimestamp

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

GetHashCode()

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

HappenedBefore(HlcTimestamp)

Determines whether this timestamp happened before another timestamp.

public bool HappenedBefore(HlcTimestamp other)

Parameters

other HlcTimestamp

The timestamp to compare against.

Returns

bool

True if this timestamp causally precedes other, false otherwise.

Remarks

Implements the happened-before relation (→):

this → other if:
  - this.PhysicalTimeNanos < other.PhysicalTimeNanos, OR
  - this.PhysicalTimeNanos == other.PhysicalTimeNanos AND this.LogicalCounter < other.LogicalCounter

IsConcurrentWith(HlcTimestamp)

Determines whether this timestamp is concurrent with another timestamp.

public bool IsConcurrentWith(HlcTimestamp other)

Parameters

other HlcTimestamp

The timestamp to compare against.

Returns

bool

True if neither timestamp happened before the other (concurrent events), false otherwise.

Remarks

Concurrent timestamps indicate independent events in different causal chains. Used for conflict detection in distributed systems.

ToString()

Returns the fully qualified type name of this instance.

public override string ToString()

Returns

string

The fully qualified type name.

Operators

operator ==(HlcTimestamp, HlcTimestamp)

Equality operator.

public static bool operator ==(HlcTimestamp left, HlcTimestamp right)

Parameters

left HlcTimestamp

right HlcTimestamp

Returns

bool

operator >(HlcTimestamp, HlcTimestamp)

Greater-than operator for happened-after comparison.

public static bool operator >(HlcTimestamp left, HlcTimestamp right)

Parameters

left HlcTimestamp

right HlcTimestamp

Returns

bool

operator >=(HlcTimestamp, HlcTimestamp)

Greater-than-or-equal operator.

public static bool operator >=(HlcTimestamp left, HlcTimestamp right)

Parameters

left HlcTimestamp

right HlcTimestamp

Returns

bool

operator !=(HlcTimestamp, HlcTimestamp)

Inequality operator.

public static bool operator !=(HlcTimestamp left, HlcTimestamp right)

Parameters

left HlcTimestamp

right HlcTimestamp

Returns

bool

operator <(HlcTimestamp, HlcTimestamp)

Less-than operator for happened-before comparison.

public static bool operator <(HlcTimestamp left, HlcTimestamp right)

Parameters

left HlcTimestamp

right HlcTimestamp

Returns

bool

operator <=(HlcTimestamp, HlcTimestamp)

Less-than-or-equal operator.

public static bool operator <=(HlcTimestamp left, HlcTimestamp right)

Parameters

left HlcTimestamp

right HlcTimestamp

Returns

bool