ThrottleCraft

A Java library for controlling concurrent operations using virtual threads and semaphore-based backpressure.

Overview

ThrottleCraft provides a simple way to limit concurrent execution of tasks using Java 25 virtual threads. It implements backpressure policies to handle rate limiting scenarios.

Requirements

• Java 25 with preview features enabled
• Maven 3.9+

Core Components

VirtualThreadLimiter

Controls concurrency using semaphores and virtual threads with three backpressure policies:

• BLOCK - Blocks the caller until capacity becomes available
• TIMEOUT - Waits up to a timeout, then fails fast
• SHED - Immediately rejects if no capacity available

BackpressurePolicy

Enum defining how the system reacts when limits are reached.

Usage

// Create a limiter with max 10 concurrent tasks, TIMEOUT policy, 5 second timeout
VirtualThreadLimiter limiter = new VirtualThreadLimiter(10, BackpressurePolicy.TIMEOUT, 5_000);

// Submit a task
CompletableFuture<Result> future = limiter.submit(() -> {
    // Your task here
    return performOperation();
});

// Handle the result
future.thenAccept(result -> System.out.println(result));

// Cleanup when done
limiter.close();

Example: UserService

public class UserService {
    private final VirtualThreadLimiter limiter =
        new VirtualThreadLimiter(10, BackpressurePolicy.TIMEOUT, 5_000);

    public CompletableFuture<List<User>> fetchBatchUsers(int[] userIds) {
        return CompletableFuture.allOf(
            Arrays.stream(userIds)
                .mapToObj(id -> limiter.submit(() -> fetchSingleUser(id)))
                .toArray(CompletableFuture[]::new)
        ).thenApply(v -> /* collect results */);
    }

    public void shutdown() {
        limiter.close();
    }
}

Building

mvn clean package

Running Tests

mvn test

Configuration

The VirtualThreadLimiter constructor accepts:

• maxInFlight - Maximum number of concurrent tasks
• policy - Backpressure policy (BLOCK, TIMEOUT, or SHED)
• timeoutMs - Timeout in milliseconds (for TIMEOUT policy)

License

Apache License 2.0 - See LICENSE file for details.