Implement segregated readable/writable component interfaces and processing

Author: chrisvest

src/main/java/io/netty/buffer/api/Buf.java

@@ -15,6 +15,11 @@
  */
 package io.netty.buffer.api;
 
+import io.netty.buffer.api.ComponentProcessor.OfReadable;
+import io.netty.buffer.api.ComponentProcessor.OfWritable;
+import io.netty.buffer.api.ComponentProcessor.ReadableComponent;
+import io.netty.buffer.api.ComponentProcessor.WritableComponent;
+
 import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 
@@ -493,7 +498,7 @@ default void ensureWritable(int size) {
 
     /**
      * Get the number of "components" in this buffer, that are readable. These are the components that would be
-     * processed by {@link #forEachReadable(int, ComponentProcessor)}. For composite buffers, this is the number of
+     * processed by {@link #forEachReadable(int, OfReadable)}. For composite buffers, this is the number of
      * transitive constituent buffers that are readable, while non-composite buffers only have at most one readable
      * component.
      * <p>
@@ -506,7 +511,7 @@ default void ensureWritable(int size) {
 
     /**
      * Get the number of "components" in this buffer, that are writable. These are the components that would be
-     * processed by {@link #forEachWritable(int, ComponentProcessor)}. For composite buffers, this is the number of
+     * processed by {@link #forEachWritable(int, OfWritable)}. For composite buffers, this is the number of
      * transitive constituent buffers that are writable, while non-composite buffers only have at most one writable
      * component.
      * <p>
@@ -520,20 +525,20 @@ default void ensureWritable(int size) {
     /**
      * Process all readable components of this buffer, and return the number of components processed.
      * <p>
-     * The given {@linkplain ComponentProcessor processor} is called for each component in this buffer, and passed a
-     * component index, for the given component in the iteration, and a {@link Component} object for accessing the data
-     * within the given component.
+     * The given {@linkplain OfReadable processor} is called for each readable component in this buffer,
+     * and passed a component index, for the given component in the iteration, and a {@link ReadableComponent} object
+     * for accessing the data within the given component.
      * <p>
-     * The component index is specific to the particular invokation of this method, and may change. The first call to
-     * the consumer will be passed the given initial index, and the next call will be passed the initial index plus one,
-     * and so on.
+     * The component index is specific to the particular invokation of this method. The first call to the consumer will
+     * be passed the given initial index, and the next call will be passed the initial index plus one, and so on.
      * <p>
-     * The {@link ComponentProcessor} may stop the iteration at any time by returning {@code false}. This may cause the
-     * number of components processed to be returned as a negative number (to signal early return), and the number of
-     * components processed may then be less than the {@linkplain #countReadableComponents() readable component count}.
+     * The {@linkplain OfReadable component processor} may stop the iteration at any time by returning {@code false}.
+     * This will cause the number of components processed to be returned as a negative number (to signal early return),
+     * and the number of components processed may then be less than the
+     * {@linkplain #countReadableComponents() readable component count}.
      * <p>
-     * <strong>Note</strong> that the {@link Component} instance passed to the consumer could be reused for multiple
-     * calls, so the data must be extracted from the component in the context of the iteration.
+     * <strong>Note</strong> that the {@link ReadableComponent} instance passed to the consumer could be reused for
+     * multiple calls, so the data must be extracted from the component in the context of the iteration.
      * <p>
      * The {@link ByteBuffer} instances obtained from the component, share life time with that internal component.
      * This means they can be accessed as long as the internal memory store remain unchanged. Methods that may cause
@@ -549,14 +554,50 @@ default void ensureWritable(int size) {
      * this buffer instance.
      *
      * @param initialIndex The initial index of the iteration, and the index that will be passed to the first call to
-     *                    the {@linkplain ComponentProcessor#process(int, Component) processor}.
+     *                    the {@linkplain OfReadable#process(int, ReadableComponent) processor}.
      * @param processor The processor that will be used to process the buffer components.
      * @return The number of readable components processed, as a positive number of all readable components were
      * processed, or as a negative number if the iteration was stopped because
-     * {@link ComponentProcessor#process(int, Component)} returned {@code false}.
+     * {@link OfReadable#process(int, ReadableComponent)} returned {@code false}.
      * In any case, the number of components processed may be less than {@link #countComponents()}.
      */
-    int forEachReadable(int initialIndex, ComponentProcessor processor);
+    int forEachReadable(int initialIndex, OfReadable processor);
 
-    int forEachWritable(int initialIndex, ComponentProcessor processor);
+    /**
+     * Process all writable components of this buffer, and return the number of components processed.
+     * <p>
+     * The given {@linkplain OfWritable processor} is called for each writable component in this buffer,
+     * and passed a component index, for the given component in the iteration, and a {@link WritableComponent} object
+     * for accessing the data within the given component.
+     * <p>
+     * The component index is specific to the particular invokation of this method. The first call to the consumer will
+     * be passed the given initial index, and the next call will be passed the initial index plus one, and so on.
+     * <p>
+     * The {@link OfWritable component processor} may stop the iteration at any time by returning {@code false}.
+     * This will cause the number of components processed to be returned as a negative number (to signal early return),
+     * and the number of components processed may then be less than the
+     * {@linkplain #countReadableComponents() readable component count}.
+     * <p>
+     * <strong>Note</strong> that the {@link WritableComponent} instance passed to the consumer could be reused for
+     * multiple calls, so the data must be extracted from the component in the context of the iteration.
+     * <p>
+     * The {@link ByteBuffer} instances obtained from the component, share life time with that internal component.
+     * This means they can be accessed as long as the internal memory store remain unchanged. Methods that may cause
+     * such changes, are any method that requires the buffer to be {@linkplain #isOwned() owned}.
+     * <p>
+     * The best way to ensure this doesn't cause any trouble, is to use the buffers directly as part of the iteration,
+     * or immediately after the iteration.
+     * <p>
+     * Changes to position and limit of the byte buffers exposed via the processed components, are not reflected back to
+     * this buffer instance.
+     *
+     * @param initialIndex The initial index of the iteration, and the index that will be passed to the first call to
+     *                    the {@linkplain OfWritable#process(int, WritableComponent) processor}.
+     * @param processor The processor that will be used to process the buffer components.
+     * @return The number of writable components processed, as a positive number of all writable components were
+     * processed, or as a negative number if the iteration was stopped because
+     * {@link OfWritable#process(int, WritableComponent)} returned {@code false}.
+     * In any case, the number of components processed may be less than {@link #countComponents()}.
+     */
+    int forEachWritable(int initialIndex, OfWritable processor);
 }

src/main/java/io/netty/buffer/api/Component.java

@@ -15,7 +15,155 @@
  */
 package io.netty.buffer.api;
 
-@FunctionalInterface
+import java.nio.ByteBuffer;
+
+/**
+ * This interface contain a collection of APIs used in the {@link Buf#forEachReadable(int, OfReadable)} and
+ * {@link Buf#forEachWritable(int, OfWritable)} methods.
+ */
 public interface ComponentProcessor {
-    boolean process(int index, Component component);
+    /**
+     * A processor of {@linkplain ReadableComponent readable components}.
+     */
+    @FunctionalInterface
+    interface OfReadable extends ComponentProcessor {
+        /**
+         * Process the given component at the given index in the {@link Buf#forEachReadable(int, OfReadable) iteration}.
+         * <p>
+         * The component object itself is only valid during this call, but the {@link ByteBuffer byte buffers}, arrays,
+         * and native address pointers obtained from it, will be valid until any
+         * {@link Buf#isOwned() ownership} requiring operation is performed on the buffer.
+         *
+         * @param index The current index of the given buffer component, based on the initial index passed to the
+         *              {@link Buf#forEachReadable(int, OfReadable)} method.
+         * @param component The current buffer component being processed.
+         * @return {@code true} if the iteration should continue and more components should be processed, otherwise
+         * {@code false} to stop the iteration early.
+         */
+        boolean process(int index, ReadableComponent component);
+    }
+
+    /**
+     * A processor of {@linkplain WritableComponent writable components}.
+     */
+    @FunctionalInterface
+    interface OfWritable extends ComponentProcessor {
+        /**
+         * Process the given component at the given index in the
+         * {@link Buf#forEachWritable(int, OfWritable)}  iteration}.
+         * <p>
+         * The component object itself is only valid during this call, but the {@link ByteBuffer byte buffers}, arrays,
+         * and native address pointers obtained from it, will be valid until any
+         * {@link Buf#isOwned() ownership} requiring operation is performed on the buffer.
+         *
+         * @param index The current index of the given buffer component, based on the initial index passed to the
+         *              {@link Buf#forEachWritable(int, OfWritable)} method.
+         * @param component The current buffer component being processed.
+         * @return {@code true} if the iteration should continue and more components should be processed, otherwise
+         * {@code false} to stop the iteration early.
+         */
+        boolean process(int index, WritableComponent component);
+    }
+
+    /**
+     * A view onto the buffer component being processed in a given iteration of
+     * {@link Buf#forEachReadable(int, OfReadable)}.
+     */
+    interface ReadableComponent {
+
+        /**
+         * Check if this component is backed by a cached byte array than can be accessed cheaply.
+         * <p>
+         * <strong>Note</strong> that regardless of what this method returns, the array should not be used to modify the
+         * contents of this buffer component.
+         *
+         * @return {@code true} if {@link #readableArray()} is a cheap operation, otherwise {@code false}.
+         */
+        boolean hasReadableArray();
+
+        /**
+         * Get a byte array of the contents of this component.
+         * <p>
+         * <strong>Note</strong> that the array is meant to be read-only. It may either be a direct reference to the
+         * concrete array instance that is backing this component, or it is a fresh copy.
+         * Writing to the array may produce undefined behaviour.
+         *
+         * @return A byte array of the contents of this component.
+         * @throws UnsupportedOperationException if {@link #hasReadableArray()} returns {@code false}.
+         */
+        byte[] readableArray();
+
+        /**
+         * An offset into the {@link #readableArray()} where this component starts.
+         *
+         * @return An offset into {@link #readableArray()}.
+         * @throws UnsupportedOperationException if {@link #hasReadableArray()} returns {@code false}.
+         */
+        int readableArrayOffset();
+
+        /**
+         * Give the native memory address backing this buffer, or return 0 if this buffer has no native memory address.
+         * <p>
+         * <strong>Note</strong> that the address should not be used for writing to the buffer memory, and doing so may
+         * produce undefined behaviour.
+         *
+         * @return The native memory address, if any, otherwise 0.
+         */
+        long readableNativeAddress();
+
+        /**
+         * Get a {@link ByteBuffer} instance for this memory component.
+         * <p>
+         * <strong>Note</strong> that the {@link ByteBuffer} is read-only, to prevent write accesses to the memory,
+         * when the buffer component is obtained through {@link Buf#forEachReadable(int, OfReadable)}.
+         *
+         * @return A new {@link ByteBuffer} for this memory component.
+         */
+        ByteBuffer readableBuffer();
+    }
+
+    /**
+     * A view onto the buffer component being processed in a given iteration of
+     * {@link Buf#forEachWritable(int, OfWritable)}.
+     */
+    interface WritableComponent {
+
+        /**
+         * Check if this component is backed by a cached byte array than can be accessed cheaply.
+         *
+         * @return {@code true} if {@link #writableArray()} is a cheap operation, otherwise {@code false}.
+         */
+        boolean hasWritableArray();
+
+        /**
+         * Get a byte array of the contents of this component.
+         *
+         * @return A byte array of the contents of this component.
+         * @throws UnsupportedOperationException if {@link #hasWritableArray()} returns {@code false}.
+         */
+        byte[] writableArray();
+
+        /**
+         * An offset into the {@link #writableArray()} where this component starts.
+         *
+         * @return An offset into {@link #writableArray()}.
+         * @throws UnsupportedOperationException if {@link #hasWritableArray()} returns {@code false}.
+         */
+        int writableArrayOffset();
+
+        /**
+         * Give the native memory address backing this buffer, or return 0 if this buffer has no native memory address.
+         *
+         * @return The native memory address, if any, otherwise 0.
+         */
+        long writableNativeAddress();
+
+        /**
+         * Get a {@link ByteBuffer} instance for this memory component, which can be used for modifying the buffer
+         * contents.
+         *
+         * @return A new {@link ByteBuffer} for this memory component.
+         */
+        ByteBuffer writableBuffer();
+    }
 }

src/main/java/io/netty/buffer/api/ComponentProcessor.java

@@ -740,7 +740,7 @@ public int countWritableComponents() {
     }
 
     @Override
-    public int forEachReadable(int initialIndex, ComponentProcessor processor) {
+    public int forEachReadable(int initialIndex, ComponentProcessor.OfReadable processor) {
         checkReadBounds(readerOffset(), Math.max(1, readableBytes()));
         int visited = 0;
         for (Buf buf : bufs) {
@@ -758,7 +758,7 @@ public int forEachReadable(int initialIndex, ComponentProcessor processor) {
     }
 
     @Override
-    public int forEachWritable(int initialIndex, ComponentProcessor processor) {
+    public int forEachWritable(int initialIndex, ComponentProcessor.OfWritable processor) {
         checkWriteBounds(writerOffset(), Math.max(1, writableBytes()));
         int visited = 0;
         for (Buf buf : bufs) {