程序包 com.darra.ethercat.sugar

类 MasterAsync

java.lang.Object

com.darra.ethercat.sugar.MasterAsync

public final class MasterAsync
extends Object

Java 8+ CompletableFuture 异步语法糖.

主线 EtherCATMaster.setStateAsync(com.darra.ethercat.data.EcState) 已存在, 但功能单一. 本类把一组 阻塞 API (setNetwork, scan, configureDC, applyStartup) 都转成 CompletableFuture, 方便用 thenCompose / thenApply / whenComplete / orTimeout 组合.

底层用专用守护线程池 (默认 4 线程, 小于 ForkJoinPool.commonPool, 防止跟 Java 应用其他任务竞争). 所有线程 daemon=true, 进程退出不阻塞.

典型用法:

 // 1. 串行: 设网卡 -> 进 OP -> 启动 PDO
 MasterAsync.setNetworkAsync(master, primary, secondary)
     .thenCompose(ok -> MasterAsync.setStateAsync(master, EcState.OP, Duration.ofSeconds(15)))
     .thenAccept(ok -> System.out.println("OP=" + ok));

 // 2. 带超时
 boolean op = MasterAsync.setStateAsync(master, EcState.OP)
     .orTimeout(10, TimeUnit.SECONDS)
     .exceptionally(t -> false)
     .join();

 // 3. 并行扫描多张网卡
 CompletableFuture<Integer> a = MasterAsync.scanAsync(nicA);
 CompletableFuture<Integer> b = MasterAsync.scanAsync(nicB);
 CompletableFuture.allOf(a, b).thenRun(() ->
     System.out.printf("A=%d B=%d%n", a.join(), b.join()));
 

从以下版本开始:

2026-05

方法概要

修饰符和类型	方法	说明
static CompletableFuture<Integer>	applyStartupParametersAsync(EtherCATMaster master, byte transition, byte timing)	异步对所有从站应用启动参数.
static CompletableFuture<Boolean>	bootToOpAsync(EtherCATMaster master, String primary, String secondary)	一键启动: 网卡 -> OP -> PDO.
static CompletableFuture<Integer>	configureDCAllAsync(EtherCATMaster master, int sync0Ns, int sync1Ns)	异步配置 DC 全网.
static Executor	executor()	暴露内部线程池, 业务方可用于 thenApplyAsync(..., MasterAsync.executor()) 把回调也跑在 SDK 池里, 避免栈太深.
static CompletableFuture<Integer>	scanAsync(String adapterName)	异步扫描指定网卡上的从站数量.
static CompletableFuture<Integer>	scanRedundantAsync(String primary, String secondary)	异步扫描冗余对.
static CompletableFuture<Boolean>	setNetworkAsync(EtherCATMaster master, String primary, String secondary)	异步设置网卡.
static CompletableFuture<Boolean>	setStateAsync(EtherCATMaster master, EcState state)	异步设置主站状态.
static CompletableFuture<Boolean>	setStateAsync(EtherCATMaster master, EcState state, Duration timeout)	带超时的异步设置主站状态.

从类继承的方法 java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

方法详细资料

executor

public static Executor executor()

暴露内部线程池, 业务方可用于 thenApplyAsync(..., MasterAsync.executor()) 把回调也跑在 SDK 池里, 避免栈太深.

setStateAsync

public static CompletableFuture<Boolean> setStateAsync(EtherCATMaster master,
 EcState state)

异步设置主站状态. 等价于 EtherCATMaster.setStateAsync(EcState), 不重复包装 — 保持 SDK 主线一致.

setStateAsync

public static CompletableFuture<Boolean> setStateAsync(EtherCATMaster master,
 EcState state,
 Duration timeout)

带超时的异步设置主站状态. 超时后 future 完成 false (不抛 TimeoutException).

注意: SDK 内部 SetStateSequence 自带 5s 超时 + 3 次重试, 总共最长 ~22s. 业务超时建议 >= 25s, 否则会"看起来失败"但 SDK 仍在重试.

setNetworkAsync

public static CompletableFuture<Boolean> setNetworkAsync(EtherCATMaster master,
 String primary,
 String secondary)

异步设置网卡. 注意 setNetwork 本身是同步快速操作, 用 CompletableFuture 包装 主要是为了与后续 setStateAsync 链式组合.

scanAsync

public static CompletableFuture<Integer> scanAsync(String adapterName)

异步扫描指定网卡上的从站数量. 包装 EtherCATMaster.scanSlaveCount(String).

非阻塞: 即使扫描需要数秒 (跨网线 + 重试), 调用线程立即返回.

scanRedundantAsync

public static CompletableFuture<Integer> scanRedundantAsync(String primary,
 String secondary)

异步扫描冗余对.

configureDCAllAsync

public static CompletableFuture<Integer> configureDCAllAsync(EtherCATMaster master,
 int sync0Ns,
 int sync1Ns)

异步配置 DC 全网. 适合启动序列里和其他动作并行 (如同时启 SOEM 配置).

applyStartupParametersAsync

public static CompletableFuture<Integer> applyStartupParametersAsync(EtherCATMaster master,
 byte transition,
 byte timing)

异步对所有从站应用启动参数. 包装 EtherCATMaster.applyStartupParametersAll(byte, byte).

bootToOpAsync

public static CompletableFuture<Boolean> bootToOpAsync(EtherCATMaster master,
 String primary,
 String secondary)

一键启动: 网卡 -> OP -> PDO. 任意步骤失败 future 完成 false.

等价手写:

 setNetworkAsync(...).thenCompose(ok ->
     ok ? setStateAsync(m, EcState.OP) : completedFuture(false))
   .thenApply(ok -> { if (ok) m.start(); return ok; });