Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8139927

Improve documentation for CompletableFuture composition

    XMLWordPrintable

Details

    Description

      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.

      Attachments

        Activity

          People

            martin Martin Buchholz
            martin Martin Buchholz
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: