Package: groovy.concurrent

## [Java] Interface Pool

-     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. 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;
           });
       }

  See Also:
    AsyncScope
    ConcurrentConfig
  Since:
    6.0.0

- - ### Methods Summary

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

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `interface Executor` | `execute`
    `interface AutoCloseable` | `close`

- - ### Method Detail

    - #### public ForkJoinPool asForkJoinPool()

      Returns the underlying ForkJoinPool, if this pool is backed by one. Required for parallel stream isolation.

      throws:
        UnsupportedOperationException if this pool is not ForkJoinPool-backed (e.g., virtual thread pools)
      Returns:
        the ForkJoinPool
      Since:
        6.0.0

    - #### public void close()

      Shuts down the pool. Equivalent to shutdown().

    - #### public static Pool cpu()

      Creates a pool sized to `Runtime.availableProcessors()`, suitable for CPU-bound work.

      Returns:
        a new CPU pool

    - #### public static Pool current()

      Returns the pool bound to the current scope, or `null`.

      Set by ParallelScope.withPool using the runtime's scoped binding support.

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

    - #### public static Pool fixed(int size)

      Creates a fixed-size thread pool with daemon threads.

      throws:
        IllegalArgumentException if size ≤ 0
      Parameters:
        `size` - the number of threads (must be > 0)
      Returns:
        a new fixed pool

    - #### public int getActiveCount()

      Returns the approximate number of threads actively executing tasks.

    - #### public int getPoolSize()

      Returns the configured pool size. For virtual thread pools, returns `Integer.MAX_VALUE`.

    - #### public 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

    - #### public void shutdown()

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

    - #### public boolean usesVirtualThreads()

      Returns `true` if this pool uses virtual threads.

    - #### public 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

    - #### <T> public static T withCurrent(Pool pool, Supplier<T> supplier)

      Executes the supplier with the given pool as current, restoring the previous binding afterwards.

      Parameters:
        `pool` - the pool to bind
        `supplier` - the work to execute
      Type Parameters:
        `T` - the result type
      Returns:
        the supplier's result
      Since:
        6.0.0