Class HeartbeatMonitor

java.lang.Object
cloud.opencode.base.event.monitor.HeartbeatMonitor
All Implemented Interfaces:
AutoCloseable
public class HeartbeatMonitor extends Object implements AutoCloseable
Generic heartbeat monitor that detects missed heartbeats. 通用心跳监控器，用于检测心跳超时。

Watches registered items and fires a callback when an item has not sent a heartbeat within its expected interval. Uses a single virtual thread for periodic checks.

监控已注册项目，当某项目在其期望间隔内未发送心跳时触发回调。 使用单个虚拟线程进行周期性检查。

Usage | 用法:

HeartbeatMonitor monitor = HeartbeatMonitor.builder()
    .checkPeriod(Duration.ofSeconds(30))
    .onMissed(id -> log.warn("Heartbeat missed: {}", id))
    .build();

monitor.watch("service-a", Duration.ofMinutes(1));
monitor.start();

// In the monitored component:
monitor.heartbeat("service-a");

// On shutdown:
monitor.stop();

Features | 主要功能:

  • Periodic heartbeat checking - 周期性心跳检查
  • Missed heartbeat detection - 心跳超时检测
  • Virtual thread based - 基于虚拟线程

Usage Examples | 使用示例:

HeartbeatMonitor monitor = HeartbeatMonitor.builder()
    .checkPeriod(Duration.ofSeconds(30))
    .onMissed(id -> log.warn("Heartbeat missed: {}", id))
    .build();

monitor.watch("service-a", Duration.ofMinutes(1));
monitor.start();

// In the monitored component:
monitor.heartbeat("service-a");

// On shutdown:
monitor.stop();

Security | 安全性:

  • Thread-safe: Yes (concurrent data structures) - 线程安全: 是（并发数据结构）
Since:
JDK 25, opencode-base-event V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • builder

      public static HeartbeatMonitor.Builder builder()
      Create a new builder. 创建新的构建器。
      Returns:
      a new builder instance / 新的构建器实例

    • watch

      public void watch(String id, Duration expectedInterval)
      Register an item to be watched for missed heartbeats. 注册一个需要监控心跳的项目。

      The clock starts from the moment of registration, so the first missed callback fires only if no heartbeat arrives within expectedInterval.

      时钟从注册时刻开始计时，仅当在 expectedInterval 内未收到心跳时 才触发首次超时回调。

      Parameters:
      id - the unique identifier of the watched item / 被监控项目的唯一标识符
      expectedInterval - maximum time between heartbeats / 心跳之间的最大时间间隔
      Throws:
      NullPointerException - if id or expectedInterval is null / 如果 id 或 expectedInterval 为 null

    • heartbeat

      public void heartbeat(String id)
      Record a heartbeat for the given item. 为指定项目记录一次心跳。
      Parameters:
      id - the unique identifier of the watched item / 被监控项目的唯一标识符
      Throws:
      NullPointerException - if id is null / 如果 id 为 null

    • unwatch

      public void unwatch(String id)
      Stop watching the given item. 停止监控指定项目。
      Parameters:
      id - the unique identifier of the watched item / 被监控项目的唯一标识符

    • getMissedIds

      public Set<String> getMissedIds()
      Return the IDs of items that have missed their heartbeat (exceeded their expected interval). 返回已超时（超出期望间隔）的项目ID集合。
      Returns:
      immutable set of missed item IDs / 超时项目ID的不可变集合

    • watchedCount

      public int watchedCount()
      Return the number of items currently being watched. 返回当前正在监控的项目数量。
      Returns:
      watched item count / 被监控项目数量

    • start

      public void start()
      Start the periodic heartbeat checker. 启动周期性心跳检查。

      Uses a virtual thread for the scheduled check loop.

      使用虚拟线程执行定时检查循环。

    • stop

      public void stop()
      Stop the periodic heartbeat checker. 停止周期性心跳检查。

    • close

      public void close()
      Alias for stop(), implements AutoCloseable. stop() 的别名，实现 AutoCloseable。
      Specified by:
      close in interface AutoCloseable