RFR: 8291023: FileOutputStream.close() re-entrantly invokes itself via FileChannel.close() [v2]

[Brian Burkhalter]

On Fri, 7 Apr 2023 14:16:32 GMT, Archie L. Cobbs <duke at openjdk.org> wrote:

>> IO stream classes like `FileOutputStream` can have assocated NIO channels.
>> 
>> When `close()` is invoked on one of these classes, it in turn invokes `close()` on the associated channel (if any). But when the associated channel's `close()` method is invoked, it in turn invokes `close()` on the associated stream (if any).
>> 
>> As a result, these IO stream `close()` methods invoke themselves reentrantly when there is an associated channel.
>> 
>> This is not a problem for these classes because they are written to handle this (i.e., they are idempotent), but it can be surprising (or worse, just silently bug-inducing) for subclasses that override `close()`.
>> 
>> There are two possible ways to address this:
>> 1. Modify the code to detect and avoid the (unnecessary) reentrant invocations
>> 2. Add a `@implNote` to the Javadoc so subclass implementers are made aware
>> 
>> This patch takes the second, more conservative approach.
>
> Archie L. Cobbs has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Apply Javadoc improvements suggested in review.

Perhaps the issue summary / PR title should be more like this?

Clarify reentrant behavior of the close method of FileInputStream, FileOutputStream, and RandomAccessFile

-------------

PR Comment: https://git.openjdk.org/jdk/pull/13379#issuecomment-1500409211