Package com.tnsai.coordination.choreography

Class LivelockDetector

java.lang.Object
com.tnsai.coordination.choreography.LivelockDetector
public final class LivelockDetector extends Object
Detects livelock conditions in multi-agent systems.

Unlike deadlocks where agents are stuck waiting, livelocks occur when agents keep changing state without making real progress. This detector identifies three patterns:

  • Repeated messages: Same message sent N times within a time window
  • Oscillating states: State flip-flops between values (A→B→A→B)
  • Progress stalls: No new unique actions observed within a time window

When the total violation count exceeds the circuit breaker threshold, the detector trips and stops accepting new events until explicitly reset.

Usage Example


 LivelockDetector detector = LivelockDetector.builder()
     .repeatThreshold(5)
     .repeatWindow(Duration.ofSeconds(10))
     .oscillationThreshold(4)
     .stallWindow(Duration.ofSeconds(30))
     .circuitBreakerThreshold(3)
     .build();

 detector.recordMessage("agent-1", "retry-task-X");
 detector.recordStateChange("agent-2", "IDLE");

 LivelockDetector.DetectionResult result = detector.analyze();
 if (result.hasLivelock()) {
     result.violations().forEach(v -> log.warn("Livelock: {}", v));
 }
See Also:

  • Method Details

    • recordMessage

      public void recordMessage(String agentId, String messageContent)
      Records a message sent by an agent.
      Parameters:
      agentId - the agent that sent the message
      messageContent - the message content (or a fingerprint/hash of it)
      Throws:
      IllegalStateException - if the circuit breaker is tripped

    • recordStateChange

      public void recordStateChange(String agentId, String newState)
      Records a state change for an agent.
      Parameters:
      agentId - the agent whose state changed
      newState - the new state value
      Throws:
      IllegalStateException - if the circuit breaker is tripped

    • recordAction

      public void recordAction(String agentId, String action)
      Records an action performed by an agent for progress tracking.
      Parameters:
      agentId - the agent that performed the action
      action - the action identifier
      Throws:
      IllegalStateException - if the circuit breaker is tripped

    • analyze

      public LivelockDetector.DetectionResult analyze()
      Analyzes all recorded events and returns a detection result.

      If violations are found and the total violation count exceeds the circuit breaker threshold, the circuit breaker trips and no further events can be recorded until reset() is called.

      Returns:
      detection result with any found violations

    • reset

      public void reset()
      Resets the circuit breaker and clears all recorded history.

    • isCircuitBroken

      public boolean isCircuitBroken()
      Returns whether the circuit breaker is currently tripped.
      Returns:
      true if the circuit breaker is active

    • getViolationCount

      public int getViolationCount()
      Returns the cumulative violation count since the last reset.
      Returns:
      violation count

    • addListener

      public void addListener(LivelockDetector.LivelockListener listener)
      Adds a listener that is notified when livelock is detected.
      Parameters:
      listener - the listener to add

    • removeListener

      public void removeListener(LivelockDetector.LivelockListener listener)
      Removes a previously added listener.
      Parameters:
      listener - the listener to remove

    • builder

      public static LivelockDetector.Builder builder()
      Creates a new builder with sensible defaults.
      Returns:
      new builder