Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 4 commits into from

Conversation

Hamlin-Li
Copy link

@Hamlin-Li Hamlin-Li commented Feb 1, 2021

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

Download

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

@bridgekeeper
Copy link

bridgekeeper bot commented Feb 1, 2021

👋 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 openjdk bot added the rfr Pull request is ready for review label Feb 1, 2021
@openjdk
Copy link

openjdk bot commented Feb 1, 2021

@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
Copy link
Contributor

/label add nit

@AlanBateman
Copy link
Contributor

/label add nio

@openjdk
Copy link

openjdk bot commented Feb 1, 2021

@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 openjdk bot added the nio nio-dev@openjdk.org label Feb 1, 2021
@openjdk
Copy link

openjdk bot commented Feb 1, 2021

@AlanBateman
The nio label was successfully added.

@mlbridge
Copy link

mlbridge bot commented Feb 1, 2021

Webrevs

@Hamlin-Li 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
@Hamlin-Li
Copy link
Author

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I will remove this @APinote addition

* 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.
*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

@Hamlin-Li Hamlin-Li Feb 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, will modify as you suggested.

@Hamlin-Li
Copy link
Author

@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

@@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@AlanBateman
Copy link
Contributor

/csr

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

openjdk bot commented Feb 3, 2021

@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
Copy link
Author

Hamlin-Li commented Feb 4, 2021

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.

@AlanBateman
Copy link
Contributor

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
Copy link
Author

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
Copy link
Member

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 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
@Hamlin-Li
Copy link
Author

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 openjdk bot removed the csr Pull request needs approved CSR before integration label Feb 19, 2021
@openjdk
Copy link

openjdk bot commented Feb 19, 2021

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

@openjdk openjdk bot added the ready Pull request is ready to be integrated label Feb 19, 2021
@Hamlin-Li
Copy link
Author

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

@AlanBateman
Copy link
Contributor

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

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

@Hamlin-Li
Copy link
Author

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
Copy link
Author

/integrate

@openjdk openjdk bot closed this Feb 19, 2021
@openjdk 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
@openjdk
Copy link

openjdk bot commented Feb 19, 2021

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

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.

@Hamlin-Li Hamlin-Li deleted the api-note-in-transferFrom branch February 26, 2021 04:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
integrated Pull request has been integrated nio nio-dev@openjdk.org
4 participants