Issue #6728 - QUIC and HTTP/3

- Improved code comments.

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

jetty-quic/quic-client/src/main/java/org/eclipse/jetty/quic/client/ClientProtocolSession.java

@@ -75,6 +75,8 @@ public class ClientProtocolSession extends ProtocolSession
     @Override
     public Runnable getProducerTask()
     {
+        // On the client, the contract is that applications should not block inside API callback methods,
+        // so a call to produce() should never block, and we can return a NON_BLOCKING producer task.
         return producer;
     }
 

jetty-quic/quic-common/src/main/java/org/eclipse/jetty/quic/common/ProtocolSession.java

@@ -71,6 +71,9 @@ public abstract class ProtocolSession extends ContainerLifeCycle
 
     protected void produce()
     {
+        // This method may be called concurrently, but the ExecutionStrategy guarantees
+        // that only one active thread is the producer thread for this ProtocolSession.
+        // On the server, this guarantees a "thread per active connection" model.
         if (LOG.isDebugEnabled())
             LOG.debug("processing {}", this);
         strategy.produce();

jetty-quic/quic-server/src/main/java/org/eclipse/jetty/quic/server/ServerProtocolSession.java

@@ -67,6 +67,11 @@ public class ServerProtocolSession extends ProtocolSession
     @Override
     public Runnable getProducerTask()
     {
+        // On the server, a call to produce() may process a stream which then parses a request,
+        // which then typically produces a blocking task that calls the application, which may
+        // be run by the ExecutionStrategy and therefore block the current thread.
+        // The producer task is always blocking to provide a "thread per active connection"
+        // model similar to what happens on the server with TCP networking.
         return producer;
     }