--- 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);
}