JDK-8260694: (fc) Clarify FileChannel.transferFrom to better describe "no bytes available" case #2329

Hamlin-Li · 2021-02-01T02:26:23Z

We'd better put more detailed messages in FileChannel.transferFrom/transferTo that it will not return -1, as we met several cases where developers of framework/program assume that it will return -1 on some error conditions, e.g. EOF of src Channel of transferFrom.

please check more details in JDK-8260486, and discussion in https://mail.openjdk.java.net/pipermail/nio-dev/2021-January/008094.html

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

JDK-8260694: (fc) Clarify FileChannel.transferFrom to better describe "no bytes available" case

Reviewers

Alan Bateman (@AlanBateman - Reviewer)

Download

$ git fetch https://git.openjdk.java.net/jdk pull/2329/head:pull/2329
$ git checkout pull/2329

bridgekeeper · 2021-02-01T02:26:47Z

👋 Welcome back mli! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2021-02-01T02:27:50Z

@Hamlin-Li To determine the appropriate audience for reviewing this pull request, one or more labels corresponding to different subsystems will normally be applied automatically. However, no automatic labelling rule matches the changes in this pull request. In order to have an "RFR" email sent to the correct mailing list, you will need to add one or more applicable labels manually using the /label pull request command.

Applicable Labels

2d
awt
beans
build
compiler
core-libs
hotspot
hotspot-compiler
hotspot-gc
hotspot-jfr
hotspot-runtime
i18n
javadoc
jdk
jmx
kulla
net
nio
security
serviceability
shenandoah
sound
swing

AlanBateman · 2021-02-01T11:20:43Z

/label add nit

AlanBateman · 2021-02-01T11:20:54Z

/label add nio

openjdk · 2021-02-01T11:20:57Z

@AlanBateman The label nit is not a valid label. These labels are valid:

serviceability
hotspot
sound
hotspot-compiler
kulla
i18n
shenandoah
jdk
javadoc
2d
security
swing
hotspot-runtime
jmx
build
nio
beans
core-libs
compiler
net
hotspot-gc
hotspot-jfr
awt

openjdk · 2021-02-01T11:21:08Z

@AlanBateman
The nio label was successfully added.

mlbridge · 2021-02-01T11:24:54Z

Webrevs

04: Full - Incremental (5039f26)
03: Full - Incremental (b9ab224)
02: Full - Incremental (b198ce6)
01: Full - Incremental (91233c7)
00: Full (c9ed084b76c6a30e1dbb4e565d3fad991bee63a6)

Hamlin-Li · 2021-02-02T01:05:53Z

interesting, why it keeps failing? I just modified the javadoc in the patch. is this an environment issue?

…escribe "no bytes available" case

AlanBateman · 2021-02-02T08:35:31Z

src/java.base/share/classes/java/nio/channels/FileChannel.java

+     * @apiNote
+     * This method only returns the number of bytes that were actually
+     * transferred, it will not return -1.
+     *


The transferTo method is file -> target channel and I think it would be confusing to mention -1 here.
We could add an apiNote to point out that the method returns zero if the given position is greater than the file's current size, and also zero if the target channel is non-blocking and has no bytes free in its output buffer, but I think the javadoc is already clear.

OK, I will remove this @APinote addition

AlanBateman · 2021-02-02T08:39:16Z

src/java.base/share/classes/java/nio/channels/FileChannel.java

+     * This method only returns the number of bytes that were actually
+     * transferred, it will not return -1, e.g. in case of EOF of the
+     * {@code src} parameter.
+     *


Looking at this again, I think it may be better if we just add a sentence to the end of the second paragraph of the method description. The second paragraph already covers the case that fewer bytes are transferred. I think it can be something simple like "No bytes are transferred if the source channel has reached end-of-stream". I suggest "end-of-stream" rather than "EOF" because that is the phrase used in the RBC javadoc.

Hi Alan, Thanks for reviewing.
I will add the sentence you suggested at the end of second paragraph, will use "end-of-stream".
Still think it's better to add an apiNote, although it's a little redundant, but it helps emphasize it, I saw several cases of misunderstanding of transferFrom. How do you think about it?

Given the other verbiage I don't think that an apiNote is actually necessary.

Hi Brian,
At the beginning, I don't think this patch is necessary, because I think if I read really carefully, then I can avoid the misuse.
But the truth is there are several misuse cases, not just in my company, several are in opensource projects. So, I think it's worth to emphasize it even if it's a little redudant.
How do you think about it?

The transferXXX methods return the number of bytes that were transferred to or from the file so there should be no expectation that -1 is returned. My preference would be to just clarify the transferFrom javadoc to make it clear that zero is returned when the source has reached end-of-stream.

OK, I have removed the apiNote and only refine the javadoc as Brian suggested.
Would you mind to take another look? Thanks

…escribe "no bytes available" case

bplb · 2021-02-03T02:05:37Z

src/java.base/share/classes/java/nio/channels/FileChannel.java

@@ -642,7 +642,8 @@ public abstract long transferTo(long position, long count,
     * number of bytes will be transferred if the source channel has fewer than
     * {@code count} bytes remaining, or if the source channel is non-blocking
     * and has fewer than {@code count} bytes immediately available in its
-     * input buffer.
+     * input buffer. No bytes are transferred if the source channel has reached
+     * end-of-stream.


How about * end-of-stream in which case zero will be returned.?

Sure, will modify as you suggested.

Hamlin-Li · 2021-02-03T05:30:13Z

@AlanBateman @bplb Hi Alan, Brian, do you know how can I avoid the failures in pre-submit tests? I don't think my patch will introduce the failures, any clue or suggestion?
Thanks

…escribe "no bytes available" case

AlanBateman · 2021-02-03T14:07:55Z

src/java.base/share/classes/java/nio/channels/FileChannel.java

@@ -642,7 +642,8 @@ public abstract long transferTo(long position, long count,
     * number of bytes will be transferred if the source channel has fewer than
     * {@code count} bytes remaining, or if the source channel is non-blocking
     * and has fewer than {@code count} bytes immediately available in its
-     * input buffer.
+     * input buffer. No bytes are transferred if the source channel has reached
+     * the end-of-stream in which case zero will be returned.


Thanks for dropping the apiNote that mentions -1 and return value.

The update is mostly okay, I might re-word it slightly to "No bytes are transferred, and zero is returned, if the source has reached end-of-stream".

Thanks Alan, just modified as you suggested, I think it's better.

AlanBateman · 2021-02-03T14:08:05Z

/csr

openjdk · 2021-02-03T14:08:12Z

@AlanBateman has indicated that a compatibility and specification (CSR) request is needed for this pull request.
@Hamlin-Li please create a CSR request and add link to it in JDK-8260694. This pull request cannot be integrated until the CSR request is approved.

Hamlin-Li · 2021-02-04T08:11:47Z

Hi Alan, CSR is created at https://bugs.openjdk.java.net/browse/JDK-8261135. Thanks
BTW, seems linux x86 fails often, I think it's safe for me to ignore the failures, please kindly let me know otherwise.

…escribe "no bytes available" case

AlanBateman · 2021-02-04T14:20:31Z

Hi Alan, CSR is created at https://bugs.openjdk.java.net/browse/JDK-8261135. Thanks

Thanks, I've tweaked it a bit and reduced the specification section down to the changes that we have agreed in the PR. You should be able to hit "Finalize".

BTW, seems linux x86 fails often, I think it's safe for me to ignore the failures, please kindly let me know otherwise.

Sorry, I can't help on this as I haven't built on 32-bit for several years. There are a few people in OpenJDK that are keeping the 32-bit builds working.

Hamlin-Li · 2021-02-05T00:49:09Z

Hi Alan, CSR is created at https://bugs.openjdk.java.net/browse/JDK-8261135. Thanks

Thanks, I've tweaked it a bit and reduced the specification section down to the changes that we have agreed in the PR. You should be able to hit "Finalize".

Thanks Alan, just finalized it.

BTW, seems linux x86 fails often, I think it's safe for me to ignore the failures, please kindly let me know otherwise.

Sorry, I can't help on this as I haven't built on 32-bit for several years. There are a few people in OpenJDK that are keeping the 32-bit builds working.
Got it.

FrauBoes · 2021-02-11T16:56:40Z

Hi @Hamlin-Li, to move this forward, could you re-finalize the CSR and change the title of this PR in line with the CSR and issue?

Hamlin-Li · 2021-02-19T00:48:11Z

Hi @Hamlin-Li, to move this forward, could you re-finalize the CSR and change the title of this PR in line with the CSR and issue?

Hi Julia,
Thanks for reminding. I have just changed the pr title and re-finalized the CSR.
( Sorry for the delayed reply, I have been on a long vacation. )

openjdk · 2021-02-19T02:24:24Z

@Hamlin-Li This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8260694: (fc) Clarify FileChannel.transferFrom to better describe "no bytes available" case

Reviewed-by: alanb

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 415 new commits pushed to the master branch:

c158413: 8261098: Add clhsdb "findsym" command
0c31d5b: 8261977: Fix comment for getPrefixed() in canonicalize_md.c
9cf4f90: 8261473: Shenandoah: Add breakpoint support
c4664e6: 8261940: Fix references to IOException in BigDecimal javadoc
0e9c5ae: 8075909: [TEST_BUG] The regression-swing case failed as it does not have the 'Open' button when select 'subdir' folder with NimbusLAF
e9f3aab: 8261912: Code IfNode::fold_compares_helper more defensively
fd098e7: 8261838: Shenandoah: reconsider heap region iterators memory ordering
f94a845: 8261600: NMT: Relax memory order for updating MemoryCounter and fix racy updating of peak values
1a7adc8: 8260416: Remove unused method ReferenceProcessor::is_mt_processing_set_up()
3a21e1d: 8260653: Unreachable nodes keep speculative types alive
... and 405 more: https://git.openjdk.java.net/jdk/compare/35c9da70316da21a6be2fd92a5e5b5f193bdd9d6...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

Hamlin-Li · 2021-02-19T06:18:48Z

Seems it's ready, am I good to integrate the change?

AlanBateman · 2021-02-19T08:28:41Z

Seems it's ready, am I good to integrate the change?

Yes, good to go, enter "/integrate" or use pr integrate.

Hamlin-Li · 2021-02-19T12:34:43Z

Seems it's ready, am I good to integrate the change?

Yes, good to go, enter "/integrate" or use pr integrate.

Thanks Alan.

Hamlin-Li · 2021-02-19T12:34:57Z

/integrate

openjdk · 2021-02-19T12:35:57Z

@Hamlin-Li Since your change was applied there have been 423 commits pushed to the master branch:

1b0c36b: 8261649: AArch64: Optimize LSE atomics in C++ code
61820b7: 8259984: IGV: Crash when drawing control flow before GCM
7e2c909: 8260485: Simplify and unify handler vectors in Posix signal code
c99eeb0: 8260858: Implementation specific property xsltcIsStandalone for XSLTC Serializer
5caf686: 8261644: NMT: Simplifications and cleanups
ed93bc9: 8196301: java/awt/print/PrinterJob/Margins.java times out
7e78c77: 8261905: Move implementation of OopStorage num_dead related functions
78cde64: 8261860: Crash caused by lambda proxy class loaded in Shutdown hook
c158413: 8261098: Add clhsdb "findsym" command
0c31d5b: 8261977: Fix comment for getPrefixed() in canonicalize_md.c
... and 413 more: https://git.openjdk.java.net/jdk/compare/35c9da70316da21a6be2fd92a5e5b5f193bdd9d6...master

Your commit was automatically rebased without conflicts.

Pushed as commit a180a38.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

openjdk bot added the rfr Pull request is ready for review label Feb 1, 2021

openjdk bot added the nio nio-dev@openjdk.org label Feb 1, 2021

Hamlin-Li changed the title ~~JDK-8260694: (fc) put clear message in FileChannel.transferFrom/transferTo that it will not return -1~~ JDK-8260694: (fc) Add apiNote to FileChannel.transferFrom to better describe "no bytes available" case Feb 1, 2021

JDK-8260694: (fc) Add apiNote to FileChannel.transferFrom to better d…

91233c7

…escribe "no bytes available" case

Hamlin-Li force-pushed the api-note-in-transferFrom branch from c9ed084 to 91233c7 Compare February 2, 2021 04:12

AlanBateman reviewed Feb 2, 2021

View reviewed changes

JDK-8260694: (fc) Add apiNote to FileChannel.transferFrom to better d…

b198ce6

…escribe "no bytes available" case

bplb reviewed Feb 3, 2021

View reviewed changes

JDK-8260694: (fc) Add apiNote to FileChannel.transferFrom to better d…

b9ab224

…escribe "no bytes available" case

AlanBateman reviewed Feb 3, 2021

View reviewed changes

openjdk bot added the csr Pull request needs approved CSR before integration label Feb 3, 2021

JDK-8260694: (fc) Add apiNote to FileChannel.transferFrom to better d…

5039f26

…escribe "no bytes available" case

AlanBateman approved these changes Feb 4, 2021

View reviewed changes

Hamlin-Li changed the title ~~JDK-8260694: (fc) Add apiNote to FileChannel.transferFrom to better describe "no bytes available" case~~ JDK-8260694: (fc) Clarify FileChannel.transferFrom to better describe "no bytes available" case Feb 19, 2021

openjdk bot removed the csr Pull request needs approved CSR before integration label Feb 19, 2021

openjdk bot added the ready Pull request is ready to be integrated label Feb 19, 2021

openjdk bot closed this Feb 19, 2021

openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Feb 19, 2021

Hamlin-Li deleted the api-note-in-transferFrom branch February 26, 2021 04:22

JDK-8260694: (fc) Clarify FileChannel.transferFrom to better describe "no bytes available" case #2329

JDK-8260694: (fc) Clarify FileChannel.transferFrom to better describe "no bytes available" case #2329

Hamlin-Li commented Feb 1, 2021 •

edited by openjdk bot

bridgekeeper bot commented Feb 1, 2021

openjdk bot commented Feb 1, 2021

AlanBateman commented Feb 1, 2021

AlanBateman commented Feb 1, 2021

openjdk bot commented Feb 1, 2021

openjdk bot commented Feb 1, 2021

mlbridge bot commented Feb 1, 2021 •

edited

Hamlin-Li commented Feb 2, 2021

AlanBateman Feb 2, 2021

Hamlin-Li Feb 3, 2021

AlanBateman Feb 2, 2021

Hamlin-Li Feb 3, 2021 •

edited

bplb Feb 3, 2021

Hamlin-Li Feb 3, 2021

AlanBateman Feb 3, 2021

Hamlin-Li Feb 3, 2021

bplb Feb 3, 2021

Hamlin-Li Feb 3, 2021

Hamlin-Li commented Feb 3, 2021

AlanBateman Feb 3, 2021

Hamlin-Li Feb 4, 2021

AlanBateman commented Feb 3, 2021

openjdk bot commented Feb 3, 2021

Hamlin-Li commented Feb 4, 2021 •

edited

AlanBateman commented Feb 4, 2021

Hamlin-Li commented Feb 5, 2021

FrauBoes commented Feb 11, 2021

Hamlin-Li commented Feb 19, 2021

openjdk bot commented Feb 19, 2021 •

edited

Hamlin-Li commented Feb 19, 2021

AlanBateman commented Feb 19, 2021

Hamlin-Li commented Feb 19, 2021

Hamlin-Li commented Feb 19, 2021

openjdk bot commented Feb 19, 2021

JDK-8260694: (fc) Clarify FileChannel.transferFrom to better describe "no bytes available" case #2329

JDK-8260694: (fc) Clarify FileChannel.transferFrom to better describe "no bytes available" case #2329

Conversation

Hamlin-Li commented Feb 1, 2021 • edited by openjdk bot

Progress

Issue

Reviewers

Download

bridgekeeper bot commented Feb 1, 2021

openjdk bot commented Feb 1, 2021

AlanBateman commented Feb 1, 2021

AlanBateman commented Feb 1, 2021

openjdk bot commented Feb 1, 2021

openjdk bot commented Feb 1, 2021

mlbridge bot commented Feb 1, 2021 • edited

Webrevs

Hamlin-Li commented Feb 2, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Hamlin-Li Feb 3, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Hamlin-Li commented Feb 3, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AlanBateman commented Feb 3, 2021

openjdk bot commented Feb 3, 2021

Hamlin-Li commented Feb 4, 2021 • edited

AlanBateman commented Feb 4, 2021

Hamlin-Li commented Feb 5, 2021

FrauBoes commented Feb 11, 2021

Hamlin-Li commented Feb 19, 2021

openjdk bot commented Feb 19, 2021 • edited

Hamlin-Li commented Feb 19, 2021

AlanBateman commented Feb 19, 2021

Hamlin-Li commented Feb 19, 2021

Hamlin-Li commented Feb 19, 2021

openjdk bot commented Feb 19, 2021

Hamlin-Li commented Feb 1, 2021 •

edited by openjdk bot

mlbridge bot commented Feb 1, 2021 •

edited

Hamlin-Li Feb 3, 2021 •

edited

Hamlin-Li commented Feb 4, 2021 •

edited

openjdk bot commented Feb 19, 2021 •

edited