RFR: 8293839: Documentation memory consistency effects of runLater [v2]

[Nir Lisker]

On Thu, 15 Sep 2022 11:52:00 GMT, Jens Lidestrom <duke at openjdk.org> wrote:

>> Prior to this change it was not clear from the documentation if callers of Platform#runLater must perform
>> any synchronisation to have writes of the calling thread be visible in the JavaFX Application
>> Thread. It is important to document either if callers can rely on runLater to do such synchronisation
>> internally, or to document is users CAN NOT rely on runLater for this.
>> 
>> This change documents that actions in a thread prior to submitting a runnable to
>> Platform#runLater happen-before actions performed by the runnable in the JavaFX
>> Application Thread.
>> 
>> runLater inherits the memory consistency effects of InvokeLaterDispatcher in most cases. 
>> InvokeLaterDispatcher uses BlockingDeque internally. This change documents this
>> in the same way as it is documented by BlockingDeque.
>> 
>> Other implementations of runLater should have similar memory consistency effects.
>
> Jens Lidestrom has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Use code formatting for 'runnable'

modules/javafx.graphics/src/main/java/javafx/application/Platform.java line 156:

> 154:      * <p>
> 155:      * Memory consistency effects: Actions in a thread prior to submitting a
> 156:      * runnable to this method <i>happen-before</i> actions performed by

I noticed that other classes add the link to the concurrency package summary as in https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/util/concurrent/BlockingQueue.html

You might want to do so as well.

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

PR: https://git.openjdk.org/jfx/pull/872