Class Actor<T>
java.lang.Object
com.sure.tool.thread.Actor<T>
- Type Parameters:
T- 消息类型
轻量 Actor 模型:消息驱动的并发单元,Hutool / Guava / Apache Commons 三家均无的独占能力。
每个 Actor 拥有独立邮箱与一个虚拟线程消息循环:
- 顺序消费:消息按投递顺序被
handler逐个处理; - 错误隔离:单条消息处理异常不中断消息循环,仅回调
errorHandler(可缺省); - 优雅关闭:
close()后拒绝新消息,已入队消息全部处理完毕才退出; - 邮箱策略:无界(默认)或有界(可配容量,满时投递抛异常或限时等待);
- 全部公开方法线程安全。
示例:
Actor<String> logger = Actor.start(msg -> System.out.println("收到: " + msg));
logger.send("hello");
logger.send("world");
logger.close();
- Since:
- 1.19.0
- Author:
- suretool
-
Method Summary
Modifier and TypeMethodDescriptionvoidclose()优雅关闭:拒绝新消息,已入队消息全部处理完毕后消息循环退出;幂等。booleanisClosed()是否已关闭。int当前待处理消息数(诊断/监控用途)。void异步投递一条消息(非阻塞)。static <T> Actor<T> 启动一个无界邮箱 Actor,消息在独立虚拟线程上被顺序消费。static <T> Actor<T> 启动一个邮箱容量受限的 Actor(容量 ≤ 0 视为无界)。static <T> Actor<T> 启动一个带错误回调的 Actor(容量 ≤ 0 视为无界)。boolean限时投递一条消息:在指定时间内成功入队返回true,超时返回false。
-
Method Details
-
start
启动一个无界邮箱 Actor,消息在独立虚拟线程上被顺序消费。示例:
Actor<Integer> actor = Actor.start(n -> System.out.println("n = " + n)); actor.send(1);- Type Parameters:
T- 消息类型- Parameters:
handler- 消息处理器,不允许为null- Returns:
- 已启动的 Actor
- Throws:
IllegalArgumentException- handler 为null时抛出
-
start
启动一个邮箱容量受限的 Actor(容量 ≤ 0 视为无界)。示例:
Actor<String> actor = Actor.start(s -> { }, 16);- Type Parameters:
T- 消息类型- Parameters:
handler- 消息处理器,不允许为nullcapacity- 邮箱容量,≤ 0 表示无界- Returns:
- 已启动的 Actor
- Throws:
IllegalArgumentException- handler 为null时抛出
-
start
public static <T> Actor<T> start(Consumer<T> handler, int capacity, Consumer<Throwable> errorHandler) 启动一个带错误回调的 Actor(容量 ≤ 0 视为无界)。单条消息处理异常不中断消息循环;
errorHandler为null时异常被忽略。示例:
Actor<String> actor = Actor.start(msg -> { throw new RuntimeException("boom"); }, 16, t -> System.err.println("处理异常: " + t)); actor.send("x");- Type Parameters:
T- 消息类型- Parameters:
handler- 消息处理器,不允许为nullcapacity- 邮箱容量,≤ 0 表示无界errorHandler- 消息处理异常回调,可为null- Returns:
- 已启动的 Actor
- Throws:
IllegalArgumentException- handler 为null时抛出
-
send
异步投递一条消息(非阻塞)。无界邮箱恒成功;有界邮箱已满时抛出
IllegalStateException。 需要限时等待入队请使用trySend(Object, Duration)。示例:
Actor<String> actor = Actor.start(s -> { }); actor.send("ping");- Parameters:
message- 消息,不允许为null- Throws:
NullPointerException- message 为null时抛出IllegalStateException- Actor 已关闭或邮箱已满时抛出
-
trySend
限时投递一条消息:在指定时间内成功入队返回true,超时返回false。适用于有界邮箱的背压控制;
timeout为null视为立即尝试。示例:
Actor<String> actor = Actor.start(s -> { }, 1); boolean ok = actor.trySend("ping", Duration.ofMillis(100));- Parameters:
message- 消息,不允许为nulltimeout- 等待时限,null视为立即尝试- Returns:
- 成功入队返回
true,超时返回false - Throws:
NullPointerException- message 为null时抛出IllegalStateException- Actor 已关闭时抛出
-
close
public void close()优雅关闭:拒绝新消息,已入队消息全部处理完毕后消息循环退出;幂等。关闭后
send(T)与trySend(T, Duration)抛出IllegalStateException。示例:
Actor<String> actor = Actor.start(s -> { }); actor.send("flush"); actor.close(); -
isClosed
public boolean isClosed()是否已关闭。- Returns:
- 已关闭返回
true
-
pendingCount
public int pendingCount()当前待处理消息数(诊断/监控用途)。- Returns:
- 邮箱中尚未被消费的消息数
-