Updates from review.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>

jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/HttpClientTransport.java

@@ -88,6 +88,7 @@ public interface HttpClientTransport extends ClientConnectionFactory, HttpClient
 
     /**
      * @return the {@link InvocationType} associated with this {@code HttpClientTransport}.
+     * @see #setInvocationType(InvocationType)
      */
     @Override
     default InvocationType getInvocationType()
@@ -96,7 +97,38 @@ default InvocationType getInvocationType()
     }
 
     /**
+     * <p>Sets the {@link InvocationType} associated with this {@code HttpClientTransport}.</p>
+     * <p>The values are typically either:
+     * <ul>
+     *   <li>{@link InvocationType#BLOCKING}, to indicate that response listeners are
+     *   executing blocking code, for example blocking network I/O, JDBC, etc.</li>
+     *   <li>{@link InvocationType#NON_BLOCKING}, to indicate that response listeners
+     *   are executing non-blocking code.</li>
+     * </ul>
+     * <p>By default, the value is {@link InvocationType#BLOCKING}.</p>
+     * <p>A response listener declared to be {@link InvocationType#BLOCKING} incurs
+     * in one additional context switch, where the NIO processing thread delegates
+     * the response processing to another thread.
+     * This ensures that the NIO processing thread can immediately continue with
+     * other NIO processing activities, if any (for example, processing another
+     * connection).
+     * This also means that processing of different connections is parallelized.</p>
+     * <p>{@link InvocationType#BLOCKING} must be used when you want response
+     * listeners to be invoked by virtual threads.</p>
+     * <p>On the other hand, a response listener declared to be
+     * {@link InvocationType#NON_BLOCKING} does not incur in the additional
+     * context switch, and therefore it is potentially more efficient.
+     * However, the processing of different connections is serialized, which
+     * means that the last connection will be processed only after the previous
+     * connections (and their respective response listeners) have been processed.</p>
+     * <p>A response listener declared to be {@link InvocationType#NON_BLOCKING},
+     * but then executing blocking code, will block the NIO processing performed
+     * by {@link HttpClient}'s implementation: the current connection and possibly
+     * other connections will not be further processed, until the blocking response
+     * listener returns.</p>
+     *
      * @param invocationType the {@link InvocationType} associated with this {@code HttpClientTransport}.
+     * @see #getInvocationType()
      */
     void setInvocationType(InvocationType invocationType);
 }

jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/transport/HttpClientTransportOverHTTP.java

@@ -26,12 +26,11 @@
 import org.eclipse.jetty.io.EndPoint;
 import org.eclipse.jetty.util.annotation.ManagedAttribute;
 import org.eclipse.jetty.util.annotation.ManagedObject;
-import org.eclipse.jetty.util.thread.Invocable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 @ManagedObject("The HTTP/1.1 client transport")
-public class HttpClientTransportOverHTTP extends AbstractConnectorHttpClientTransport implements Invocable
+public class HttpClientTransportOverHTTP extends AbstractConnectorHttpClientTransport
 {
     public static final Origin.Protocol HTTP11 = new Origin.Protocol(List.of("http/1.1"), false);
     private static final Logger LOG = LoggerFactory.getLogger(HttpClientTransportOverHTTP.class);

jetty-core/jetty-http2/jetty-http2-client-transport/src/main/java/org/eclipse/jetty/http2/client/transport/HttpClientTransportOverHTTP2.java

@@ -42,10 +42,9 @@
 import org.eclipse.jetty.util.Promise;
 import org.eclipse.jetty.util.annotation.ManagedAttribute;
 import org.eclipse.jetty.util.annotation.ManagedObject;
-import org.eclipse.jetty.util.thread.Invocable;
 
 @ManagedObject("The HTTP/2 client transport")
-public class HttpClientTransportOverHTTP2 extends AbstractHttpClientTransport implements Invocable
+public class HttpClientTransportOverHTTP2 extends AbstractHttpClientTransport
 {
     private final ClientConnectionFactory connectionFactory = new HTTP2ClientConnectionFactory();
     private final HTTP2Client http2Client;

jetty-core/jetty-http3/jetty-http3-client-transport/src/main/java/org/eclipse/jetty/http3/client/transport/HttpClientTransportOverHTTP3.java

@@ -39,9 +39,8 @@
 import org.eclipse.jetty.quic.client.QuicTransport;
 import org.eclipse.jetty.quic.common.ProtocolSession;
 import org.eclipse.jetty.quic.common.QuicSession;
-import org.eclipse.jetty.util.thread.Invocable;
 
-public class HttpClientTransportOverHTTP3 extends AbstractHttpClientTransport implements ProtocolSession.Factory, Invocable
+public class HttpClientTransportOverHTTP3 extends AbstractHttpClientTransport implements ProtocolSession.Factory
 {
     private final HTTP3ClientConnectionFactory factory = new HTTP3ClientConnectionFactory();
     private final HTTP3Client http3Client;