Improve comments.

git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1672057 13f79535-47bb-0310-9956-ffa450edef68
apache · Apr 8, 2015 · 7a7fb86 · 7a7fb86
1 parent cdf544e
commit 7a7fb86
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 20 deletions.
diff --git a/java/org/apache/tomcat/util/net/Nio2Endpoint.java b/java/org/apache/tomcat/util/net/Nio2Endpoint.java
@@ -1044,17 +1044,14 @@ public void close() throws IOException {
         }
 
         // TODO: NIO2 style scatter/gather methods.
-        // TODO: SecureNio2Channel scatter/gather would need to be improved
 
         public enum CompletionState {
             /**
-             * Operation is pending and the completion handler will
-             * be called later.
+             * Operation is still pending.
              */
             PENDING,
             /**
-             * The operation completed inline, and the completion handler
-             * will not be called unless an error occurred.
+             * The operation completed inline.
              */
             INLINE,
             /**
@@ -1071,12 +1068,12 @@ public enum CompletionHandlerCall {
             CONTINUE,
             /**
              * The operation completed but the completion handler shouldn't be
-             * called. This is possibly useful if the operation completed
-             * inline.
+             * called.
              */
             NONE,
             /**
-             * The operation is complete, call the completion handler.
+             * The operation is complete, the completion handler should be
+             * called.
              */
             DONE
         }
@@ -1263,8 +1260,9 @@ public CompletionHandlerCall callHandler(CompletionState state, ByteBuffer[] buf
          * data has been read or an error occurred. If a CompletionCheck
          * object has been provided, the completion handler will only be
          * called if the callHandler method returned true. If no
-         * CompletionCheck object has been provided, the completion handler
-         * will be called.
+         * CompletionCheck object has been provided, the ddefault NIO2
+         * behavior is used: the completion handler will be called as soon
+         * as some data has been read, even if the read has completed inline.
          *
          * @param dsts buffers
          * @param offset in the buffer array
@@ -1277,11 +1275,9 @@ public CompletionHandlerCall callHandler(CompletionState state, ByteBuffer[] buf
          * @return the completion state (done, done inline, or still pending)
          */
         // FIXME: @Override
-        public <A> CompletionState read(ByteBuffer[] dsts,
-                int offset, int length,
+        public <A> CompletionState read(ByteBuffer[] dsts, int offset, int length,
                 long timeout, TimeUnit unit, A attachment,
-                CompletionCheck check,
-                CompletionHandler<Long, ? super A> handler) {
+                CompletionCheck check, CompletionHandler<Long, ? super A> handler) {
             OperationState<A> state = new OperationState<>(dsts, offset, length, timeout, unit, attachment, check, handler);
             if (readPending.tryAcquire()) {
                 Nio2Endpoint.startInline();
@@ -1293,6 +1289,7 @@ public <A> CompletionState read(ByteBuffer[] dsts,
             return state.state;
         }
 
+        // FIXME: @Override
         public boolean isWritePending() {
             synchronized (writeCompletionHandler) {
                 return writePending.availablePermits() == 0;
@@ -1304,8 +1301,10 @@ public boolean isWritePending() {
          * data has been written or an error occurred. If a CompletionCheck
          * object has been provided, the completion handler will only be
          * called if the callHandler method returned true. If no
-         * CompletionCheck object has been provided, the completion handler
-         * will be called.
+         * CompletionCheck object has been provided, the ddefault NIO2
+         * behavior is used: the completion handler will be called, even
+         * if the write is incomplete and data remains in the buffers, or
+         * if the write completed inline.
          *
          * @param srcs buffers
          * @param offset in the buffer array
@@ -1318,11 +1317,9 @@ public boolean isWritePending() {
          * @return the completion state (done, done inline, or still pending)
          */
         // FIXME: @Override
-        public <A> CompletionState write(ByteBuffer[] srcs,
-                int offset, int length,
+        public <A> CompletionState write(ByteBuffer[] srcs, int offset, int length,
                 long timeout, TimeUnit unit, A attachment,
-                CompletionCheck check,
-                CompletionHandler<Long, ? super A> handler) {
+                CompletionCheck check, CompletionHandler<Long, ? super A> handler) {
             OperationState<A> state = new OperationState<>(srcs, offset, length, timeout, unit, attachment, check, handler);
             if (writePending.tryAcquire()) {
                 Nio2Endpoint.startInline();

diff --git a/java/org/apache/tomcat/util/net/SecureNio2Channel.java b/java/org/apache/tomcat/util/net/SecureNio2Channel.java
@@ -793,6 +793,7 @@ public <A> void read(final ByteBuffer dst,
         }
     }
 
+    // TODO: Possible optimization for scatter
     @Override
     public <A> void read(ByteBuffer[] dsts, int offset, int length,
             long timeout, TimeUnit unit, A attachment,
@@ -957,6 +958,7 @@ public void failed(Throwable exc, GatherState<A> attachment) {
         }
     }
 
+    // TODO: Possible optimization for gather
     @Override
     public <A> void write(ByteBuffer[] srcs, int offset, int length,
             long timeout, TimeUnit unit, A attachment,