-
Bug
-
Resolution: Fixed
-
P3
-
9
-
b107
The thenCompose family of methods is hard to understand and the documentation could be better. Specifically:
"""An additional form (compose) applies functions of stages themselves, rather than their results."""
This is not quite correct - the functions RETURN stages; they are not arguments, as strongly suggested here.
---
http://download.java.net/jdk9/docs/api/java/util/concurrent/CompletionStage.html#thenCompose-java.util.function.Function-
We should clarify the relationship between the future returned by the method and the future returned by the supplied function. In fact, they are connected by a relay; the returned future completes when the other completes, with the same value.
Current documentation talks about stages being "executed", but that is imprecise and confusing. Methods are executed; futures are completed.
---
It would be good if there were some tutorial information here, as with the excellent examples in CountedCompleter. There is a already a cottage industry already producing such tutorials, often using the dreaded "M" word, but none are authoritative.
"""An additional form (compose) applies functions of stages themselves, rather than their results."""
This is not quite correct - the functions RETURN stages; they are not arguments, as strongly suggested here.
---
http://download.java.net/jdk9/docs/api/java/util/concurrent/CompletionStage.html#thenCompose-java.util.function.Function-
We should clarify the relationship between the future returned by the method and the future returned by the supplied function. In fact, they are connected by a relay; the returned future completes when the other completes, with the same value.
Current documentation talks about stages being "executed", but that is imprecise and confusing. Methods are executed; futures are completed.
---
It would be good if there were some tutorial information here, as with the excellent examples in CountedCompleter. There is a already a cottage industry already producing such tutorials, often using the dreaded "M" word, but none are authoritative.