compareTo method

  1. @override
int compareTo(
  1. Pulse other
)
override

Compares this pulse with another to determine relative execution precedence.

When to use

  • Execution Precedence: You rarely call this directly — the framework uses it for ordering pulses in the dispatcher.
  • Custom sorting of pulses.
  • Testing or debugging order.
  • Implementing custom dispatchers.

How it works

  1. Primary: Chronological order (earlier timestamps first).
  2. Secondary: Priority (higher priority first).
  3. Tertiary: Trace depth (shallower traces first).

This multi-tier sorting strategy ensures deterministic ordering in the reactive stream, maintaining Causal Integrity and system state reproducibility.

Parameters:

  • other: The pulse to compare with.

Returns:

A negative value if this pulse has higher precedence, a positive value if lower precedence, or zero if they are equal.

Implementation

@override
int compareTo(Pulse other) {
  if (identical(this, other)) {
    return 0;
  }

  final timeComparison = timestamp.compareTo(other.timestamp);
  if (timeComparison != 0) {
    return timeComparison;
  }

  final thisPriority = priority;
  final otherPriority = other.priority;
  final priorityComparison = otherPriority.compareTo(thisPriority);
  if (priorityComparison != 0) {
    return priorityComparison;
  }

  return _kernal.trace.length.compareTo(other.trace.length);
}