程序包 com.darra.ethercat.master

类 AsyncGate

java.lang.Object
com.darra.ethercat.master.AsyncGate
所有已实现的接口:
AutoCloseable
public final class AsyncGate extends Object implements AutoCloseable
==================================================================== [2026-06-11 异步隔离层 — 核心串行闸 (1:1 对齐 C# AsyncGate.cs)]

设计目标 (用户架构指令): 阻塞操作的隔离必须做在 SDK 层, 由 SDK 主动提供 异步/非阻塞 API, 让所有用 SDK 的人 (GUI + 第三方客户) 都不卡线程。不能只在 GUI 层包装 (那样直接用 SDK 的客户照样卡)。

本类是异步层的"唯一串行闸": 每个 master 持有一把 serialExecutor = 单线程 ExecutorService, 所有 *Async 方法都经 runExclusiveAsync(java.lang.String, java.util.function.Supplier<T>) 进入, 用这个单线程把本主站所有 EtherCAT 操作【串行排队执行】 — 即使多个调用方并发提交, 也按到达顺序逐个跑, 绝不并发 打总线 (并发会乱总线/竞态)。这等价于 C# 的 SemaphoreSlim(1,1): 容量 1 = 任意时刻最多 1 个 EtherCAT 操作在跑; 单线程 executor 在 Java 里语义更干净 (天然 FIFO 串行 + JNI 阻塞调用全在这一根线程, 调用方线程绝不堵)。

隔离手段: 把同步 native 调用 (build/setState/scan/SDO) 丢到单线程后台跑, 调用方拿 CompletableFuture 不堵。后台异常通过 future 正常抛回 (不吞没)。取消时调 DarraCore.AbortNetwork() 让仍在 native 内阻塞的 调用立即返回 (JVM 无法强杀 JNI 阻塞调用, 只能让 native 主动中止), 随后 复位 abort latch (DarraCore.ResetAbortNetwork()) 否则 latch 残留会毒化取消之后的 build/setState (帧被 native 当 abort 直接失败)。

shutdown 守门: master close() 时调 shutdown() 置 shuttingDown=true 并停 executor。已排队但还没进 native 的任务在进 native 前查此标志 → 抛 CancellationException, 防 use-after-free (排队期间 native 上下文可能已被 close/dispose 释放)。

⚠ 仅新增隔离层, 不改任何现有同步 API 的行为/签名。同步方法继续可用 (向后兼容, 第三方老代码不破)。

线程模型注意 (与 C# 一致): 进度回调 / future 后续回调默认在 executor 线程 (非调用方主线程) 触发。Swing 需自己 SwingUtilities.invokeLater, JavaFX 需 Platform.runLater, 才能安全更新 UI 控件。

====================================================================

  • 方法详细资料

    • forMaster

      public static AsyncGate forMaster(short masterIndex)
      按 masterIndex 反查父 master 的串行闸 (SDO 异步用, 跨包 slave 调用); 未注册返回 null。

      public 因 com.darra.ethercat.slave.CoE 需跨包按 masterIndex 反查父闸 (Slave 不持父 master 对象引用, 只持 masterIndex)。

    • isShuttingDown

      public boolean isShuttingDown()
      当前是否处于关闭中 (诊断用)。

    • runExclusiveAsync

      public <T> CompletableFuture<T> runExclusiveAsync(String operationName, Supplier<T> body)
      串行隔离执行一个同步 EtherCAT 操作 (带返回值)。
      • ① 提交到本主站单线程 executor → 与本主站其它 async 操作 FIFO 串行 (等闸)。
      • ② 同步体在后台单线程跑, 调用方拿 future 不堵线程。
      • ③ 进 native 前查 shuttingDown (BUG-2 防 use-after-free): 排队期间 master 可能已被 close。
      • ④ cancelFuture 触发 (用户对返回的 future 调 cancel(true)) → 调 native AbortNetwork 让阻塞中的 native 立即返回, 随后复位 abort latch (BUG-4)。
      • ⑤ 后台异常通过 future 原样抛回 (不吞没)。
      类型参数:
      T - 返回类型
      参数:
      operationName - 操作名 (日志/诊断用)
      body - 要在后台串行执行的同步操作体 (直接调现有同步 API)
      返回:
      CompletableFuture; 取消返回的 future (cancel(true)) 会中止 native 阻塞操作

    • runExclusiveAsync

      public CompletableFuture<Void> runExclusiveAsync(String operationName, Runnable body)
      串行隔离执行一个同步 EtherCAT 操作 (无返回值)。语义同 runExclusiveAsync(String, Supplier)。

    • runStaticExclusiveAsync

      public static <T> CompletableFuture<T> runStaticExclusiveAsync(String operationName, Supplier<T> body)
      静态版串行隔离执行 (语义同实例 runExclusiveAsync(String, Supplier), 但用进程级 STATIC_SCAN_EXECUTOR + 扫描专用 abort flag)。供 scanAsync 等没有 master 实例的 静态阻塞操作用。
      类型参数:
      T - 返回类型
      参数:
      operationName - 操作名 (日志用)
      body - 扫描操作体
      返回:
      CompletableFuture; 取消返回的 future 会打"扫描"专用 abort flag (AbortScan)

    • shutdown

      public void shutdown()
      master close() 时调用: 置 shuttingDown=true (拦后续 async 进 native), 停 executor, 注销注册表项。幂等 (重复调用安全)。

    • close

      public void close()
      指定者:
      close 在接口中 AutoCloseable