Merge pull request quarkusio#41410 from mkouba/issue-41393

WebSockets Next: document WebSocket#inboundProcessingMode()

docs/src/main/asciidoc/websockets-next-reference.adoc

@@ -521,6 +521,15 @@ void pong(Buffer data) {
 
 NOTE: The server/client can also send unsolicited pong messages that may serve as a unidirectional heartbeat. There is a non-blocking variant: `WebSocketConnection#sendPong(Buffer)` and also a blocking variant: `WebSocketConnection#sendPongAndAwait(Buffer)`.
 
+[[inbound-processing-mode]]
+=== Inbound processing mode
+
+WebSocket endpoints can define the mode used to process incoming events for a specific connection using the `@WebSocket#inboundProcessingMode()`, and `@WebSocketClient.inboundProcessingMode()` respectively. 
+An incoming event can represent a message (text, binary, pong), opening connection and closing connection.
+By default, events are processed serially and ordering is guaranteed.
+This means that if an endpoint receives events `A` and `B` (in this particular order) then callback for event `B` will be invoked after the callback for event `A` completed.
+However, in some situations it is preferable to process events concurrently, i.e. with no ordering guarantees but also with no concurrency limits.
+For this cases, the `InboundProcessingMode#CONCURRENT` should be used.
 
 == Server API
 

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/InboundProcessingMode.java

@@ -3,7 +3,9 @@
 import io.smallrye.common.annotation.Experimental;
 
 /**
- * Defines the mode used to process incoming messages for a specific connection.
+ * WebSocket endpoints define the mode used to process incoming events for a specific connection.
+ * <p>
+ * An incoming event can represent a message (text, binary, pong), opening connection and closing connection.
  *
  * @see WebSocketConnection
  * @see WebSocketClientConnection
@@ -12,12 +14,12 @@
 public enum InboundProcessingMode {
 
     /**
-     * Messages are processed serially, ordering is guaranteed.
+     * Events are processed serially, ordering is guaranteed.
      */
     SERIAL,
 
     /**
-     * Messages are processed concurrently, there are no ordering guarantees.
+     * Events are processed concurrently, there are no ordering guarantees.
      */
     CONCURRENT,
 

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocket.java

@@ -48,7 +48,7 @@
     public String endpointId() default FCQN_NAME;
 
     /**
-     * The mode used to process incoming messages for a specific connection.
+     * The mode used to process incoming events for a specific connection.
      */
     public InboundProcessingMode inboundProcessingMode() default InboundProcessingMode.SERIAL;
 

extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocketClient.java

@@ -48,7 +48,7 @@
     public String clientId() default FCQN_NAME;
 
     /**
-     * The execution mode used to process incoming messages for a specific connection.
+     * The mode used to process incoming events for a specific connection.
      */
     public InboundProcessingMode inboundProcessingMode() default InboundProcessingMode.SERIAL;