8146298: (dc spec) connect and disconnect methods should specify that they may block

[Brian Burkhalter]

> On Nov 13, 2019, at 12:32 AM, Alan Bateman <Alan.Bateman at oracle.com> wrote:
> 
> On 12/11/2019 20:35, Brian Burkhalter wrote:
>> :
>> 
>> Webrev [1] and CSR [2] updated. The verbiage about discarding datagrams is moved from an @implNote to normative text. There are two attachments to the CSR with the same name as the server prevented deleting the older one at this time. The CSR is moved back to draft pending comments and will be re-finalized.
>> 
> In the connect method, the paragraph "This method may be invoked ..." paragraph is about coordinating the setup of the connection with other threads that are doing send/receive at the same time. The wording is okay but the final sentence on the (potential) discarding of datagrams queued in the socket receive buffer is a separate concern and shouldn't be part of this paragraph. I think we should move it to its own paragraph or else move into the first paragraph where connected-ness is described.
> 
> I think "which have not been received" should link to #receive so that it is clearer that it means the receive method rather than received by the network/operating system. Also I think "socket receive buffer" should link to SO_RCVBUF rather than the @see so that there is something to click on the wonder comes across this a term that he/she hasn't seen before.

How about changing the first paragraph of the connect() doc to this:

     * <p> The channel's socket is configured so that it only receives
     * datagrams from, and sends datagrams to, the given remote <i>peer</i>
     * address.  Once connected, datagrams may not be received from or sent to
     * any other address.  Datagrams in the channel's {@link
     * java.net.StandardSocketOptions#SO_RCVBUF socket receive buffer}, which
     * have not been {@link #receive(ByteBuffer) received} before invoking this
     * method, may be discarded.  The channel's socket remains connected until
     * it is explicitly disconnected or until it is closed.

Having “which have not been received” as the text of a @link ends up producing what looks like one big link due to consecutive @links so I only have “received” as a link.

Brian
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/nio-dev/attachments/20191113/ee9829db/attachment.html>