Class Actor<T>

java.lang.Object
com.sure.tool.thread.Actor<T>
Type Parameters:
T - 消息类型

public final class Actor<T> extends Object
轻量 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 Type
    Method
    Description
    void
    优雅关闭:拒绝新消息,已入队消息全部处理完毕后消息循环退出;幂等。
    boolean
    是否已关闭。
    int
    当前待处理消息数(诊断/监控用途)。
    void
    send(T message)
    异步投递一条消息(非阻塞)。
    static <T> Actor<T>
    start(Consumer<T> handler)
    启动一个无界邮箱 Actor,消息在独立虚拟线程上被顺序消费。
    static <T> Actor<T>
    start(Consumer<T> handler, int capacity)
    启动一个邮箱容量受限的 Actor(容量 ≤ 0 视为无界)。
    static <T> Actor<T>
    start(Consumer<T> handler, int capacity, Consumer<Throwable> errorHandler)
    启动一个带错误回调的 Actor(容量 ≤ 0 视为无界)。
    boolean
    trySend(T message, Duration timeout)
    限时投递一条消息:在指定时间内成功入队返回 true,超时返回 false。

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • start

      public static <T> Actor<T> start(Consumer<T> handler)
      启动一个无界邮箱 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

      public static <T> Actor<T> start(Consumer<T> handler, int capacity)
      启动一个邮箱容量受限的 Actor(容量 ≤ 0 视为无界)。

      示例:

      Actor<String> actor = Actor.start(s -> { }, 16);
      
      Type Parameters:
      T - 消息类型
      Parameters:
      handler - 消息处理器,不允许为 null
      capacity - 邮箱容量,≤ 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 - 消息处理器,不允许为 null
      capacity - 邮箱容量,≤ 0 表示无界
      errorHandler - 消息处理异常回调,可为 null
      Returns:
      已启动的 Actor
      Throws:
      IllegalArgumentException - handler 为 null 时抛出
    • send

      public void send(T message)
      异步投递一条消息(非阻塞)。

      无界邮箱恒成功;有界邮箱已满时抛出 IllegalStateException。 需要限时等待入队请使用 trySend(Object, Duration)。

      示例:

      Actor<String> actor = Actor.start(s -> { });
      actor.send("ping");
      
      Parameters:
      message - 消息,不允许为 null
      Throws:
      NullPointerException - message 为 null 时抛出
      IllegalStateException - Actor 已关闭或邮箱已满时抛出
    • trySend

      public boolean trySend(T message, Duration timeout)
      限时投递一条消息:在指定时间内成功入队返回 true,超时返回 false。

      适用于有界邮箱的背压控制;timeout 为 null 视为立即尝试。

      示例:

      Actor<String> actor = Actor.start(s -> { }, 1);
      boolean ok = actor.trySend("ping", Duration.ofMillis(100));
      
      Parameters:
      message - 消息,不允许为 null
      timeout - 等待时限,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:
      邮箱中尚未被消费的消息数