changeset 55080:12c7d6b3ec28 rsocket-branch

Tweak javadoc, fix links
author alanb
date Thu, 07 Feb 2019 13:34:30 +0000
parents 81e4a12fd1a4
children c502c299d41e
files src/jdk.net/share/classes/jdk/net/RdmaSocketOptions.java src/jdk.net/share/classes/jdk/net/RdmaSockets.java
diffstat 2 files changed, 79 insertions(+), 92 deletions(-) [+]
line wrap: on
line diff
--- a/src/jdk.net/share/classes/jdk/net/RdmaSocketOptions.java	Wed Feb 06 12:48:01 2019 -0800
+++ b/src/jdk.net/share/classes/jdk/net/RdmaSocketOptions.java	Thu Feb 07 13:34:30 2019 +0000
@@ -37,7 +37,7 @@
 import java.lang.annotation.Native;
 
 /**
- * Defines socket options specific to RDMA-based TCP sockets and socket channels.
+ * Defines socket options specific to RDMA-based sockets and socket channels.
  *
  * @since 13
  */
@@ -58,55 +58,49 @@
     private RdmaSocketOptions() { }
 
     /**
-     * The integer size of the underlying RDMA send queue used by the
-     * platform for network I/O.
+     * The size of the RDMA send queue.
      *
-     * The initial/default size of the RDMA send queue and the range of
-     * allowable values is system and device dependent although a negative
-     * size is not allowed.
+     * <p> The value of this socket option is an {@code Integer} that is the size
+     * of the underlying RDMA send queue in bytes. The initial/default size of
+     * the RDMA send queue, and the range of allowable values, is system and
+     * device dependent, although a negative size is not allowed.
      *
      * <p> An implementation allows this socket option to be set before the
      * socket is bound or connected. Changing the value of this socket option
      * after the socket is bound or connected has no effect.
-     *
-     * Valid for RDMA-based TCP sockets.
      */
-    public static final SocketOption<Integer> RDMA_SQSIZE = new
-        RdmaSocketOption<Integer>("RDMA_SQSIZE", Integer.class);
+    public static final SocketOption<Integer> RDMA_SQSIZE
+        = new RdmaSocketOption<Integer>("RDMA_SQSIZE", Integer.class);
 
     /**
-     * The integer size of the underlying RDMA receive queue used by the
-     * platform for network I/O.
+     * The size of the RDMA receive queue.
      *
-     * The initial/default size of the RDMA receive queue and the range of
-     * allowable values is system and device dependent although a negative
-     * size is not allowed.
+     * <p> The value of this socket option is an {@code Integer} that is the size
+     * of the underlying RDMA receive queue in bytes. The initial/default size of
+     * the RDMA receive queue, and the range of allowable values, is system and
+     * device dependent, although a negative size is not allowed.
      *
      * <p> An implementation allows this socket option to be set before the
      * socket is bound or connected. Changing the value of this socket option
      * after the socket is bound or connected has no effect.
-     *
-     * Valid for RDMA-based TCP sockets.
      */
-    public static final SocketOption<Integer> RDMA_RQSIZE = new
-        RdmaSocketOption<Integer>("RDMA_RQSIZE", Integer.class);
+    public static final SocketOption<Integer> RDMA_RQSIZE
+        = new RdmaSocketOption<Integer>("RDMA_RQSIZE", Integer.class);
 
     /**
-     * The integer size of the underlying RDMA inline data used by the
-     * platform for network I/O.
+     * The maximum size of RDMA inline data.
      *
-     * The initial/default size of the RDMA inline data and the range of
-     * allowable values is system and device dependent although a negative
-     * size is not allowed.
+     * <p> The value of this socket option is an {@code Integer} that is the
+     * maximumm size, in bytes, of inline data. The initial/default maximum size,
+     * and the range of allowable values, is system and device dependent,
+     * although a negative size is not allowed.
      *
      * <p> An implementation allows this socket option to be set before the
      * socket is bound or connected. Changing the value of this socket option
      * after the socket is bound or connected has no effect.
-     *
-     * Valid for RDMA-based TCP sockets.
      */
-    public static final SocketOption<Integer> RDMA_INLINE = new
-        RdmaSocketOption<Integer>("RDMA_INLINE", Integer.class);
+    public static final SocketOption<Integer> RDMA_INLINE
+        = new RdmaSocketOption<Integer>("RDMA_INLINE", Integer.class);
 
     @Native private static final int SQSIZE = 0x3001;
 
--- a/src/jdk.net/share/classes/jdk/net/RdmaSockets.java	Wed Feb 06 12:48:01 2019 -0800
+++ b/src/jdk.net/share/classes/jdk/net/RdmaSockets.java	Thu Feb 07 13:34:30 2019 +0000
@@ -39,34 +39,34 @@
 import jdk.internal.net.rdma.RdmaSocketProvider;
 
 /**
- * Factory methods for creating RDMA-based TCP sockets and socket channels.
+ * This class defines static factory methods to create sockets and channels to
+ * RDMA-based sockets, and selectors to multiplex channels to RDMA sockets.
  *
- * <p>The {@link #openSocket(ProtocolFamily) openSocket} and {@link
+ * <p> The {@linkplain #openSocket(ProtocolFamily) openSocket} and {@linkplain
  * #openServerSocket(ProtocolFamily) openServerSocket} methods create RDMA-based
  * TCP sockets.
  *
- * <p>The {@link #openSelector() openSelector}, {@link
- * #openSocketChannel(ProtocolFamily) openSocketChannel}, and {@link
- * #openServerSocketChannel(ProtocolFamily) openServerSocketChannel} methods
- * create selectors and selectable channels for use with RDMA sockets. These
- * selectors and channels are created by the RDMA selector provider, which is
- * not the {@linkplain SelectorProvider#provider() default} system-wide selector
- * provider. Consequently, selectable channels to RDMA sockets may not be
- * multiplexed with selectable channels created by the default system-wide
- * selector provider. The RDMA selector provider does not support datagram
- * channels or pipes. Its {@link SelectorProvider#openDatagramChannel
- * openDatagramChannel} and {@link SelectorProvider#openPipe openPipe} methods
- * throw {@link UnsupportedOperationException UnsupportedOperationException}.
+ * <p> The {@linkplain #openSocketChannel(ProtocolFamily) openSocketChannel} and
+ * {@linkplain #openServerSocketChannel(ProtocolFamily) openServerSocketChannel}
+ * methods open {@link java.nio.channels.SelectableChannel selectable channels}
+ * to RDMA sockets. The {@linkplain #openSelector() openSelector} opens a
+ * {@linkplain Selector} for multiplexing selectable channels to RDMA sockets.
+ * Selectable channels to RDMA sockets can not be multiplexed with selectable
+ * channels opened by the default system-wide {@link SelectorProvider selector
+ * provider}. Furthermore, the RDMA selector provider does not support datagram
+ * channels or pipes; its {@linkplain SelectorProvider#openDatagramChannel
+ * openDatagramChannel} and {@linkplain SelectorProvider#openPipe openPipen}
+ * methods throw {@code UnsupportedOperationException}.
  *
- * @implNote The RDMA selector provider supports socket channels of type
- * {@link StandardProtocolFamily#INET INET} and {@link
- * StandardProtocolFamily#INET6 INET6}. Its {@link
- * SelectorProvider#openSocketChannel() openSocketChannel} and {@link
- * SelectorProvider#openServerSocketChannel() openServerSocketChannel}
- * methods create selectable channels with a family of {@link
- * StandardProtocolFamily#INET6 INET6}, if the underlying platform supports
- * IPv6. Otherwise, it creates selectable channels with a family of {@link
- * StandardProtocolFamily#INET INET}.
+ * <p> Unless otherwise noted, passing a {@code null} argument will cause a
+ * {@linkplain NullPointerException} to be thrown.
+ *
+ * @implNote The RDMA selector provider supports channels to both IPv4 and
+ * IPv6 RDMA sockets. If the no-arg {@linkplain SelectorProvider#openSocketChannel()
+ * openSocketChannel} or {@linkplain SelectorProvider#openServerSocketChannel()
+ * openServerSocketChannel} methods are used to open channels then those channels
+ * will be to IPv6 sockets if IPv6 is enabled on the platform (or IPv4 sockets
+ * if IPv6 is not enabled).
  *
  * @since 13
  */
@@ -84,17 +84,16 @@
      * {@link java.net.StandardSocketOptions#TCP_NODELAY TCP_NODELAY},
      * and those specified by {@link RdmaSocketOptions}.
      *
-     * <p> When binding the socket to a local address, or invoking {@code
-     * connect} to connect the socket, the socket address specified to those
-     * methods must correspond to the protocol family specified here.
+     * <p> When {@link Socket#bind binding} the socket to a local address, or
+     * {@link Socket#connect connecting} the socket, the socket address specified
+     * to the {@code bind} and {@code connect} methods must correspond to the
+     * protocol family specified here.
      *
-     * @param   family
-     *          The protocol family
+     * @param  family
+     *         The protocol family
      *
      * @throws IOException
      *         If an I/O error occurs
-     * @throws NullPointerException
-     *         If {@code family} is {@code null}
      * @throws UnsupportedOperationException
      *         If RDMA sockets are not supported on this platform or if the
      *         specified protocol family is not supported. For example, if
@@ -116,16 +115,14 @@
      * and those specified by {@link RdmaSocketOptions}.
      *
      * <p> When binding the socket to an address, the socket address specified
-     * to the {@code bind} method must correspond to the protocol family
-     * specified here.
+     * to the {@linkplain ServerSocket#bind bind} method must correspond to the
+     * protocol family specified here.
      *
-     * @param   family
-     *          The protocol family
+     * @param family
+     *        The protocol family
      *
      * @throws IOException
      *         If an I/O error occurs
-     * @throws NullPointerException
-     *         If {@code family} is {@code null}
      * @throws UnsupportedOperationException
      *         If RDMA sockets are not supported on this platform or if the
      *         specified protocol family is not supported. For example, if
@@ -133,17 +130,16 @@
      *         StandardProtocolFamily.INET6} but IPv6 is not enabled on the
      *         platform.
      */
-    public static ServerSocket openServerSocket(ProtocolFamily family)
-            throws IOException {
+    public static ServerSocket
+    openServerSocket(ProtocolFamily family) throws IOException {
         Objects.requireNonNull(family, "protocol family is null");
         return RdmaSocketProvider.openServerSocket(family);
     }
 
     /**
      * Opens a socket channel to an RDMA socket. A newly created socket channel
-     * is {@link SocketChannel#isOpen() open}, not yet bound to a {@link
-     * SocketChannel#getLocalAddress() local address}, and not yet
-     * {@link SocketChannel#isConnected() connected}.
+     * is {@link java.nio.channels.Channel#isOpen() open} but not yet {@link
+     * SocketChannel#bind bound} or {@link SocketChannel#isConnected() connected}.
      *
      * <p> A socket channel to an RDMA socket supports the socket options
      * {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF},
@@ -152,17 +148,16 @@
      * {@link java.net.StandardSocketOptions#TCP_NODELAY TCP_NODELAY},
      * and those specified by {@link RdmaSocketOptions}.
      *
-     * <p> When binding the channel's socket to a local address, or invoking
-     * {@code connect} to connect channel's socket, the socket address specified
-     * to those methods must correspond to the protocol family specified here.
+     * <p> When binding the channel's socket to a local address, or {@link
+     * SocketChannel#connect connecting} the channel's socket, the socket address
+     * specified to the {@code bind} and {@code connect} methods must correspond
+     * to the protocol family specified here.
      *
-     * @param   family
-     *          The protocol family
+     * @param  family
+     *         The protocol family
      *
      * @throws IOException
      *         If an I/O error occurs
-     * @throws NullPointerException
-     *         If {@code family} is {@code null}
      * @throws UnsupportedOperationException
      *         If RDMA sockets are not supported on this platform or if the
      *         specified protocol family is not supported. For example, if
@@ -170,42 +165,40 @@
      *         StandardProtocolFamily.INET6} but IPv6 is not enabled on the
      *         platform.
      */
-    public static SocketChannel openSocketChannel(ProtocolFamily family)
-            throws IOException {
+    public static SocketChannel
+    openSocketChannel(ProtocolFamily family) throws IOException {
         Objects.requireNonNull(family, "protocol family is null");
         return RdmaPollSelectorProvider.provider().openSocketChannel(family);
     }
 
     /**
-     * Opens a server socket channel to an RDMA socket. A newly created socket
-     * channel is {@link SocketChannel#isOpen() open} but not yet bound to a
-     * {@link SocketChannel#getLocalAddress() local address}.
+     * Opens a server-socket channel to an RDMA socket. A newly created
+     * server-socket is {@link java.nio.channels.Channel#isOpen() open} but not
+     * yet {@link ServerSocketChannel#bind bound}.
      *
-     * <p> A server socket channel to an RDMA server socket supports the socket
+     * <p> A server-socket channel to an RDMA server socket supports the socket
      * options {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF},
      * {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR},
      * and those specified by {@link RdmaSocketOptions}.
      *
-     * <p> When binding the channel's socket to an address, the socket address
-     * specified to the {@code bind} method must correspond to the protocol
-     * family specified here.
+     * <p> When binding the channel's socket to a local address, the address
+     * specified to the {@linkplain ServerSocketChannel#bind bind} method must
+     * correspond to the protocol family specified here.
      *
-     * @param   family
-     *          The protocol family
+     * @param  family
+     *         The protocol family
      *
      * @throws IOException
      *         If an I/O error occurs
-     * @throws NullPointerException
-     *         If {@code family} is {@code null}
      * @throws UnsupportedOperationException
-     *         If RDMA sockets are not supported on this platform or if the
+     *         If RDMA sockets are not supported on this platform or the
      *         specified protocol family is not supported. For example, if
      *         the parameter is {@link java.net.StandardProtocolFamily#INET6
      *         StandardProtocolFamily.INET6} but IPv6 is not enabled on the
      *         platform.
      */
-    public static ServerSocketChannel openServerSocketChannel(
-            ProtocolFamily family) throws IOException {
+    public static ServerSocketChannel
+    openServerSocketChannel(ProtocolFamily family) throws IOException {
         Objects.requireNonNull(family, "protocol family is null");
         return RdmaPollSelectorProvider.provider().openServerSocketChannel(family);
     }