Package groovy.concurrent

# Interface Pool

All Superinterfaces:
  `AutoCloseable`, `Executor`

All Known Implementing Classes:
  `DefaultPool`

public interface Pool extends Executor, AutoCloseable
A managed thread pool for parallel and concurrent operations.

`Pool` extends `Executor` so it can be used anywhere an executor is expected — including `AsyncScope.withScope(executor, body)`. It also implements `AutoCloseable` for use in try-with-resources blocks, ensuring clean shutdown.

Factory methods provide common pool configurations:

- `virtual()` — virtual-thread-per-task (JDK 21+), ideal for I/O
- `fixed(int)` — fixed-size thread pool with daemon threads
- `cpu()` — sized to `availableProcessors()`, for CPU-bound work
- `io()` — larger pool for I/O-bound or blocking operations

Inspired by GPars' `PGroup` pool management, modernised for virtual threads.

     try (var pool = Pool.cpu()) {
         AsyncScope.withScope(pool, scope -> {
             scope.async(() -> cpuIntensiveWork());
             scope.async(() -> moreCpuWork());
             return null;
         });
     }

Since:
  6.0.0
See Also:
  - `AsyncScope`
  - `ConcurrentConfig`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ForkJoinPool`
  `asForkJoinPool()`
  Returns the underlying `ForkJoinPool`, if this pool is backed by one.
  `default void`
  `close()`
  Shuts down the pool.
  `static Pool`
  `cpu()`
  Creates a pool sized to `Runtime.availableProcessors()`, suitable for CPU-bound work.
  `static Pool`
  `current()`
  Returns the pool bound to the current scope, or `null`.
  `static Pool`
  `fixed(int size)`
  Creates a fixed-size thread pool with daemon threads.
  `int`
  `getActiveCount()`
  Returns the approximate number of threads actively executing tasks.
  `int`
  `getPoolSize()`
  Returns the configured pool size.
  `static Pool`
  `io()`
  Creates a larger pool suitable for I/O-bound or blocking operations.
  `void`
  `shutdown()`
  Initiates an orderly shutdown.
  `boolean`
  `usesVirtualThreads()`
  Returns `true` if this pool uses virtual threads.
  `static Pool`
  `virtual()`
  Creates a virtual-thread-per-task pool (JDK 21+).
  `static <T> T`
  `withCurrent(Pool pool, Supplier<T> supplier)`
  Executes the supplier with the given pool as current, restoring the previous binding afterwards.

  ### Methods inherited from interface java.util.concurrent.Executor

  `execute`

- ## Method Details

  - ### virtual

    static Pool virtual()
    Creates a virtual-thread-per-task pool (JDK 21+).

    Each submitted task runs on its own virtual thread. This is ideal for I/O-bound workloads where tasks spend time waiting. On JDK versions that do not support virtual threads, falls back to a cached daemon thread pool.

    Returns:
      a new virtual thread pool

  - ### fixed

    static Pool fixed(int size)
    Creates a fixed-size thread pool with daemon threads.
    Parameters:
      `size` - the number of threads (must be > 0)
    Returns:
      a new fixed pool
    Throws:
      `IllegalArgumentException` - if size ≤ 0

  - ### cpu

    static Pool cpu()
    Creates a pool sized to `Runtime.availableProcessors()`, suitable for CPU-bound work.
    Returns:
      a new CPU pool

  - ### io

    static Pool io()
    Creates a larger pool suitable for I/O-bound or blocking operations.

    If virtual threads are available, returns a virtual thread pool (the ideal choice for I/O). Otherwise returns a fixed pool sized to `ConcurrentConfig.getDefaultParallelism()`.

    Returns:
      a new I/O pool

  - ### current

    static Pool current()
    Returns the pool bound to the current scope, or `null`.

    Set by `ParallelScope.withPool(int, java.util.function.Function<groovy.concurrent.AsyncScope, T>)` using the runtime's scoped binding support.

    Returns:
      the current pool, or `null` if none is bound
    Since:
      6.0.0

  - ### withCurrent

    static <T> T withCurrent(Pool pool, Supplier<T> supplier)
    Executes the supplier with the given pool as current, restoring the previous binding afterwards.
    Type Parameters:
      `T` - the result type
    Parameters:
      `pool` - the pool to bind
      `supplier` - the work to execute
    Returns:
      the supplier's result
    Since:
      6.0.0

  - ### getPoolSize

    int getPoolSize()
    Returns the configured pool size. For virtual thread pools, returns `Integer.MAX_VALUE`.

  - ### getActiveCount

    int getActiveCount()
    Returns the approximate number of threads actively executing tasks.

  - ### usesVirtualThreads

    boolean usesVirtualThreads()
    Returns `true` if this pool uses virtual threads.

  - ### asForkJoinPool

    ForkJoinPool asForkJoinPool()
    Returns the underlying `ForkJoinPool`, if this pool is backed by one. Required for parallel stream isolation.
    Returns:
      the ForkJoinPool
    Throws:
      `UnsupportedOperationException` - if this pool is not ForkJoinPool-backed (e.g., virtual thread pools)
    Since:
      6.0.0

  - ### shutdown

    void shutdown()
    Initiates an orderly shutdown. Previously submitted tasks are executed, but no new tasks will be accepted.

  - ### close

    default void close()
    Shuts down the pool. Equivalent to `shutdown()`.
    Specified by:
      `close` in interface `AutoCloseable`