Class HybridExecutor

java.lang.Object
cloud.opencode.base.parallel.executor.HybridExecutor
All Implemented Interfaces:
AutoCloseable
public final class HybridExecutor extends Object implements AutoCloseable
Hybrid Executor - Hybrid Thread Executor 混合执行器 - 混合线程执行器

An executor that maintains two thread pools: a fixed platform thread pool for CPU-bound work and a virtual thread executor for IO-bound work. Tasks implementing CpuBound are automatically dispatched to the platform thread pool; all other tasks go to the virtual thread pool.

维护两个线程池的执行器：用于 CPU 密集型工作的固定平台线程池和用于 IO 密集型工作的虚拟线程执行器。 实现 CpuBound 的任务自动分派到平台线程池；其他所有任务进入虚拟线程池。

Example | 示例:

// Default: CPU pool = availableProcessors()
try (var executor = HybridExecutor.create()) {
    executor.execute(() -> fetchFromNetwork());           // IO pool (virtual threads)
    executor.execute((CpuBound) () -> computeHash(data)); // CPU pool (platform threads)

    CompletableFuture<String> result = executor.submitOnIoPool(() -> callApi());
    CompletableFuture<Long> hash = executor.submitOnCpuPool(() -> heavyCompute());
}

// Custom configuration via builder
try (var executor = HybridExecutor.builder()
        .cpuPoolSize(4)
        .cpuThreadNamePrefix("compute-")
        .ioThreadNamePrefix("io-")
        .build()) {
    executor.execute(task);
}

Features | 主要功能:

  • Dual thread pool (platform + virtual) - 双线程池（平台+虚拟）
  • Automatic CPU/IO task dispatching - 自动CPU/IO任务分派
  • CpuBound marker interface support - CpuBound标记接口支持
  • Builder pattern configuration - 构建器模式配置

Security | 安全性:

  • Thread-safe: Yes - 线程安全: 是
Since:
JDK 25, opencode-base-parallel V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static HybridExecutor create()
      Creates a hybrid executor with default settings. 使用默认设置创建混合执行器。

      CPU pool size defaults to Runtime.getRuntime().availableProcessors().

      CPU 池大小默认为 Runtime.getRuntime().availableProcessors()。

      Returns:
      the hybrid executor - 混合执行器

    • withCpuPoolSize

      public static HybridExecutor withCpuPoolSize(int cpuPoolSize)
      Creates a hybrid executor with the specified CPU pool size. 使用指定的 CPU 池大小创建混合执行器。
      Parameters:
      cpuPoolSize - the CPU pool size - CPU 池大小
      Returns:
      the hybrid executor - 混合执行器
      Throws:
      IllegalArgumentException - if cpuPoolSize is not positive - 如果 cpuPoolSize 非正数

    • builder

      public static HybridExecutor.Builder builder()
      Creates a new builder. 创建新的构建器。
      Returns:
      the builder - 构建器

    • execute

      public void execute(Runnable task)
      Executes a runnable, auto-selecting the pool based on type. 执行 Runnable，根据类型自动选择线程池。

      If the runnable implements CpuBound, it is dispatched to the platform thread pool. Otherwise, it goes to the virtual thread pool.

      如果 Runnable 实现了 CpuBound，则分派到平台线程池。否则进入虚拟线程池。

      Parameters:
      task - the task to execute - 要执行的任务
      Throws:
      IllegalStateException - if the executor is shut down - 如果执行器已关闭

    • executeOnCpuPool

      public void executeOnCpuPool(Runnable task)
      Executes a runnable on the CPU (platform thread) pool. 在 CPU（平台线程）池上执行 Runnable。
      Parameters:
      task - the task to execute - 要执行的任务
      Throws:
      IllegalStateException - if the executor is shut down - 如果执行器已关闭

    • executeOnIoPool

      public void executeOnIoPool(Runnable task)
      Executes a runnable on the IO (virtual thread) pool. 在 IO（虚拟线程）池上执行 Runnable。
      Parameters:
      task - the task to execute - 要执行的任务
      Throws:
      IllegalStateException - if the executor is shut down - 如果执行器已关闭

    • submit

      public <T> CompletableFuture<T> submit(Callable<T> task)
      Submits a callable, auto-selecting the pool based on type. 提交 Callable，根据类型自动选择线程池。

      If the callable implements CpuBound, it is dispatched to the platform thread pool. Otherwise, it goes to the virtual thread pool.

      如果 Callable 实现了 CpuBound，则分派到平台线程池。否则进入虚拟线程池。

      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      task - the task to submit - 要提交的任务
      Returns:
      a CompletableFuture for the result - 结果的 CompletableFuture
      Throws:
      IllegalStateException - if the executor is shut down - 如果执行器已关闭

    • submitOnCpuPool

      public <T> CompletableFuture<T> submitOnCpuPool(Callable<T> task)
      Submits a callable on the CPU (platform thread) pool. 在 CPU（平台线程）池上提交 Callable。
      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      task - the task to submit - 要提交的任务
      Returns:
      a CompletableFuture for the result - 结果的 CompletableFuture
      Throws:
      IllegalStateException - if the executor is shut down - 如果执行器已关闭

    • submitOnIoPool

      public <T> CompletableFuture<T> submitOnIoPool(Callable<T> task)
      Submits a callable on the IO (virtual thread) pool. 在 IO（虚拟线程）池上提交 Callable。
      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      task - the task to submit - 要提交的任务
      Returns:
      a CompletableFuture for the result - 结果的 CompletableFuture
      Throws:
      IllegalStateException - if the executor is shut down - 如果执行器已关闭

    • getCpuSubmittedCount

      public long getCpuSubmittedCount()
      Gets the number of tasks submitted to the CPU pool. 获取提交到 CPU 池的任务数。
      Returns:
      the CPU submitted count - CPU 提交数

    • getIoSubmittedCount

      public long getIoSubmittedCount()
      Gets the number of tasks submitted to the IO pool. 获取提交到 IO 池的任务数。
      Returns:
      the IO submitted count - IO 提交数

    • getCompletedCount

      public long getCompletedCount()
      Gets the total number of completed tasks. 获取完成的任务总数。
      Returns:
      the completed count - 完成数

    • getFailedCount

      public long getFailedCount()
      Gets the total number of failed tasks. 获取失败的任务总数。
      Returns:
      the failed count - 失败数

    • isShutdown

      public boolean isShutdown()
      Checks if the executor is shut down. 检查执行器是否已关闭。
      Returns:
      true if shut down - 如果已关闭返回 true

    • shutdown

      public void shutdown()
      Shuts down both pools gracefully. 优雅地关闭两个线程池。

    • shutdownNow

      public void shutdownNow()
      Shuts down both pools immediately. 立即关闭两个线程池。

    • shutdownAndAwait

      public boolean shutdownAndAwait(Duration timeout) throws InterruptedException
      Shuts down and waits for termination of both pools. 关闭并等待两个线程池终止。
      Parameters:
      timeout - the timeout to wait - 等待超时
      Returns:
      true if both pools terminated within timeout - 如果两个池在超时内终止返回 true
      Throws:
      InterruptedException - if interrupted while waiting - 如果等待时被中断

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable