RFR: 8224974: Implement JEP 352

[Alan Bateman]

On 10/06/2019 11:09, Andrew Dinn wrote:
> :
> I have updated the Proposed Java API Changes to remove the changes to
> map exception signature and force region specification. They were
> covered in the prior enabling JIRAs/CSRs.
>
> So, the remaining two sections mention 1) the new module + package +
> enum and 2) the bean counting changes. The new section 1 clarifies when
> UnsupportedOperationException is thrown vs when IOException is thrown as
> part of the explanation of what the new modes are for.
>
> I also added a paragraph to the alternatives section explaining that
> Panama was and still is an alternative option and why we decided to
> proceed with this model despite it being still under consideration.
>
I re-read the JEP, trying to put myself in the position of someone 
reading it for the first time in 2020.

Summary section:

What would you think about replacing this with a sentence that makes it 
clear that the JEP adds new JDK-specific file mapping modes to allow the 
FileChannel API create MappedByteBuffers over non-volatile memory?

Goals section:

I think the first paragraph could be re-worded to make it clear that the 
goal is to use the existing MappedByteBuffer API to access NVM.

Paragraphs 2-5 split this into two sub-goals. The first suggests that it 
extends the MBB API but this is no longer the case. The second also 
hints that it adds a new API. I think these two need to be re-worded. 
Goal 3 and 4 are okay, although I think the 4th could be summarized as 
allowing mapped buffers on NVM to be tracked by the existing monitoring 
and management APIs.

Description section

It might be clearer of "Proposed Java API Changes" were renamed to 
"Proposed JDK-specific API changes".


One other thing to mention is that I re-read the javadoc for the MBB 
force methods and I think we need to adjust one of the sentences in the 
existing (and new) methods to take account of implementation specific 
map modes. I've created JDK-8226203 [1] to track it. As support for 
implementation specific map modes is in new in Java SE 13 then it might 
be worth trying to get that fixed now while it is fresh in our minds.

-Alan

[1] https://bugs.openjdk.java.net/browse/JDK-8226203