# Groovy Concurrent API for Java (Incubating)

version 6.0.0-alpha-1

## 1. Introduction

The `groovy-concurrent-java` module provides Groovy’s concurrent and parallel API as a standalone Java library — no Groovy runtime required.

Java developers get access to:

- Structured concurrency — `AsyncScope`, `Awaitable`

- Pools — `Pool`, `ParallelScope`, `ConcurrentConfig`

- Actors — `Actor.reactor()`, `Actor.stateful()`

- Agents — `Agent` (thread-safe mutable state)

- Dataflow — `DataflowVariable`, `AsyncChannel`, `BroadcastChannel`, `ChannelSelect`

This module is published as `org.apache.groovy:groovy-concurrent-java` and contains a filtered subset of the classes from Groovy core. It must not be used alongside the full Groovy runtime — Gradle enforces mutual exclusion via a shared capability, and a runtime warning is logged if both jars are detected on the classpath.

## 2. Setup

### 2.1. Gradle

    dependencies {
        implementation 'org.apache.groovy:groovy-concurrent-java:6.0.0'
    }

### 2.2. Maven

    <dependency>
        <groupId>org.apache.groovy</groupId>
        <artifactId>groovy-concurrent-java</artifactId>
        <version>6.0.0</version>
    </dependency>

| Do not add `groovy-concurrent-java` if you already depend on `groovy` (the full runtime). The concurrent classes are included in core.

## 3. Structured Concurrency

    import groovy.concurrent.AsyncScope;
    import groovy.concurrent.Pool;
    import org.apache.groovy.runtime.async.AsyncSupport;

    // Basic scope — waits for all children before returning
    var result = AsyncScope.withScope(scope -> {
        var a = scope.async(() -> fetchUser(id));
        var b = scope.async(() -> fetchOrders(id));
        return Map.of(
            "user", AsyncSupport.await(a),
            "orders", AsyncSupport.await(b)
        );
    });

    // With a pool for executor isolation
    try (var pool = Pool.cpu()) {
        AsyncScope.withScope(pool, scope -> {
            var task = scope.async(() -> computeResult());
            return AsyncSupport.await(task);
        });
    }

## 4. Actors

    import groovy.concurrent.Actor;
    import org.apache.groovy.runtime.async.AsyncSupport;

    // Reactor — stateless, each message produces a reply
    var doubler = Actor.<Integer, Integer>reactor(n -> n * 2);
    int result = AsyncSupport.await(doubler.sendAndGet(21)); // 42
    doubler.stop();

    // Stateful — maintains state across messages
    var counter = Actor.<String, Integer>stateful(0, (state, msg) -> {
        if ("increment".equals(msg)) return state + 1;
        return state;
    });
    counter.send("increment");
    counter.send("increment");
    int count = AsyncSupport.await(counter.sendAndGet("increment")); // 3
    counter.stop();

## 5. Agents

    import groovy.concurrent.Agent;
    import org.apache.groovy.runtime.async.AsyncSupport;

    var counter = Agent.create(0);
    counter.send(n -> n + 1);
    counter.send(n -> n + 1);
    counter.send(n -> n + 1);

    int result = AsyncSupport.await(counter.getAsync()); // 3
    counter.shutdown();

## 6. Dataflow Variables

    import groovy.concurrent.Awaitable;
    import groovy.concurrent.DataflowVariable;
    import org.apache.groovy.runtime.async.AsyncSupport;

    var x = new DataflowVariable<Integer>();
    var y = new DataflowVariable<Integer>();

    // z depends on x and y — blocks until both are bound
    var z = Awaitable.<Integer>go(() ->
        AsyncSupport.await(x) + AsyncSupport.await(y)
    );

    // Bind in any order
    AsyncSupport.getExecutor().execute(() -> x.bind(10));
    AsyncSupport.getExecutor().execute(() -> y.bind(5));

    int result = AsyncSupport.await(z); // 15

## 7. Pools

    import groovy.concurrent.ParallelScope;
    import groovy.concurrent.Pool;
    import org.apache.groovy.runtime.async.AsyncSupport;

    var result = ParallelScope.withPool(4, scope -> {
        var tasks = new java.util.ArrayList<groovy.concurrent.Awaitable<Integer>>();
        for (int i = 1; i <= 4; i++) {
            int n = i;
            tasks.add(scope.async(() -> n * 10));
        }
        int sum = 0;
        for (var task : tasks) {
            sum += (int) AsyncSupport.await(task);
        }
        return sum;
    }); // 100

## 8. Features not available in the Java module

The following features require the Groovy runtime and are only available when using the full `groovy` dependency:

Feature | Reason
--- | ---
`Dataflows` class | Uses Groovy’s `propertyMissing` for dynamic property access
`async { }` / `await` keywords | Groovy language syntax, transformed by the Groovy compiler
`defer { }` / `yield return` | Groovy language syntax
`for await (x in channel)` | Groovy compiler-generated iteration
`@ActiveObject` / `@ActiveMethod` | Groovy AST transformation
Parallel collection methods (`collectParallel`, etc.) | Registered as Groovy extension methods on `Collection`
`AsyncClosureUtils` (`wrapAsync`, `wrapAsyncGenerator`) | Return `Closure` subclasses
Closure-based APIs (e.g., `scope.async { }`) | Groovy SAM coercion from Closure to `Supplier`/`Function`

Java users have full access to the underlying APIs using `java.util.function` types (`Supplier`, `Function`, `Consumer`, `Predicate`, etc.) and explicit `AsyncSupport.await()` calls instead of the `await` keyword.