HTTPCLIENT-2394: Virtual threads support for classic client

[arturobernalg]

Introduce VirtualThreadCloseableHttpClient to run classic transport on JDK 21 virtual threads while preserving CloseableHttpClient semantics and threading contract. Extend builder with useVirtualThreads(), virtualThreadNamePrefix(), virtualThreadExecutor(...), virtualThreadShutdownWait(...), and virtualThreadsRunHandler() to control execution. Add VirtualThreadSupport utility for JDK detection and per-task executor; include example and tests. Behavior remains unchanged unless enabled via the builder.

[rschmitt]

I don't understand this at all. What problem does this solve, compared to simply calling the client from a virtual thread?

[arturobernalg]

I don't understand this at all. What problem does this solve, compared to simply calling the client from a virtual thread?

Virtual threads let blocking HttpClient scale: thousands of concurrent requests without bloated platform threads.
They avoid thread-pool exhaustion/tuning and keep the classic API—no rewrite to async.
Best under latency/IO waits (DNS, TLS, slow servers): frees carriers, improves throughput and tail latency.
Cheaper context switches and straight-line stack traces vs. async callback/Future pyramids.

[rschmitt]

Virtual threads let blocking HttpClient scale: thousands of concurrent requests without bloated platform threads.

In your example code, when you call:

            httpclient.execute(httpget, response -> { ... });

You are blocking a platform thread, which waits for the request to execute on a virtual thread. I don't see how you can realize increased concurrency in this way; it's still a thread-per-request model, and you might as well just call into the client directly from the OS thread.

The whole advantage of virtual threads over async/await is that virtual threads don't introduce function coloring. They are largely transparent to libraries. They allow everyone to write blocking, imperative code and scale up the concurrency by simply using a virtual thread factory instead of a conventional thread factory. And since HttpComponents is a pure Java library, we don't have to worry about pinning the carrier thread through blocking JNI calls or anything; Java already fixed that problem for us with JEP 353, and more recently JEP 491 made synchronized work correctly with virtual threads. I'm not sure there's a single thing we need to do to "enable" virtual threads; am I missing something here?

[arturobernalg]

Virtual threads let blocking HttpClient scale: thousands of concurrent requests without bloated platform threads.

In your example code, when you call:

            httpclient.execute(httpget, response -> { ... });

You are blocking a platform thread, which waits for the request to execute on a virtual thread. I don't see how you can realize increased concurrency in this way; it's still a thread-per-request model, and you might as well just call into the client directly from the OS thread.

The whole advantage of virtual threads over async/await is that virtual threads don't introduce function coloring. They are largely transparent to libraries. They allow everyone to write blocking, imperative code and scale up the concurrency by simply using a virtual thread factory instead of a conventional thread factory. And since HttpComponents is a pure Java library, we don't have to worry about pinning the carrier thread through blocking JNI calls or anything; Java already fixed that problem for us with JEP 353, and more recently JEP 491 made synchronized work correctly with virtual threads. I'm not sure there's a single thing we need to do to "enable" virtual threads; am I missing something here?

It’s a small, optional convenience—not a scalability silver bullet.

Virtual threads let blocking HttpClient scale: thousands of concurrent requests without bloated platform threads.

In your example code, when you call:

            httpclient.execute(httpget, response -> { ... });

You are blocking a platform thread, which waits for the request to execute on a virtual thread. I don't see how you can realize increased concurrency in this way; it's still a thread-per-request model, and you might as well just call into the client directly from the OS thread.

The whole advantage of virtual threads over async/await is that virtual threads don't introduce function coloring. They are largely transparent to libraries. They allow everyone to write blocking, imperative code and scale up the concurrency by simply using a virtual thread factory instead of a conventional thread factory. And since HttpComponents is a pure Java library, we don't have to worry about pinning the carrier thread through blocking JNI calls or anything; Java already fixed that problem for us with JEP 353, and more recently JEP 491 made synchronized work correctly with virtual threads. I'm not sure there's a single thing we need to do to "enable" virtual threads; am I missing something here?

It’s a small, optional convenience—not a scalability silver bullet.
It standardizes VT wiring (naming, shutdown), preserves classic blocking/error semantics (e.g., map executor rejection to IOException), and can also run the response handler on the same VT when requested.
Default behavior is unchanged; if you already launch calls on VTs, ignore it.
Net result: less boilerplate and consistent, documented VT behavior without coloring the API.

[ok2c]

@arturobernalg Likewise, I do not really understand the benefits of this change especially for the classic transport where the users are expected to manage the threads anyway.

I am not in favor of this change.