# HG changeset patch # User alanb # Date 1549546470 0 # Node ID 12c7d6b3ec28e6633dcfdf33f13c419700e4cc20 # Parent 81e4a12fd1a464c86a376e5241a5958c842036c3 Tweak javadoc, fix links diff -r 81e4a12fd1a4 -r 12c7d6b3ec28 src/jdk.net/share/classes/jdk/net/RdmaSocketOptions.java --- 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. + *

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. * *

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 RDMA_SQSIZE = new - RdmaSocketOption("RDMA_SQSIZE", Integer.class); + public static final SocketOption RDMA_SQSIZE + = new RdmaSocketOption("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. + *

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. * *

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 RDMA_RQSIZE = new - RdmaSocketOption("RDMA_RQSIZE", Integer.class); + public static final SocketOption RDMA_RQSIZE + = new RdmaSocketOption("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. + *

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. * *

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 RDMA_INLINE = new - RdmaSocketOption("RDMA_INLINE", Integer.class); + public static final SocketOption RDMA_INLINE + = new RdmaSocketOption("RDMA_INLINE", Integer.class); @Native private static final int SQSIZE = 0x3001; diff -r 81e4a12fd1a4 -r 12c7d6b3ec28 src/jdk.net/share/classes/jdk/net/RdmaSockets.java --- 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. * - *

The {@link #openSocket(ProtocolFamily) openSocket} and {@link + *

The {@linkplain #openSocket(ProtocolFamily) openSocket} and {@linkplain * #openServerSocket(ProtocolFamily) openServerSocket} methods create RDMA-based * TCP sockets. * - *

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}. + *

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}. + *

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}. * - *

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. + *

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}. * *

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}. * *

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}. * - *

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. + *

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}. * - *

A server socket channel to an RDMA server socket supports the socket + *

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}. * - *

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. + *

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