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

StructuredTaskScope.join description improvements

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P3
    • 21, 22
    • core-libs
    • None
    • minimal
    • Docs only change to a preview API
    • SE

    Description

      Summary

      Rephrase the description of the join and joinUntil methods defined by

      • java.util.concurrent.StructuredTaskScope
      • java.util.concurrent.StructuredTaskScope.ShutdownOnSuccess
      • java.util.concurrent.StructuredTaskScope.ShutdownOnFailure

      Problem

      StructuredTaskScope introduces the join method as waiting for all subtasks to finish. The join and joinUntil methods are phrased in terms of waiting for all threads to finish. This should be made clearer.

      The join and joinUntil methods defined by ShutdownOnSuccess and ShutdownOnFailure are inherited from the super class. It would be clearer if they overwrote the descriptions to say that they stop waiting when a task completes successfully (in the case of ShutdownOnSuccess), or fails (in the case of ShutdownOnFailure).

      Solution

      Re-phase the description of the join and joinUntil methods.

      In passing, an apiNote is added to both ShutdownOnSuccess and ShutdownOnFailure to make it clear that the shutdown method will typically not be used directly when using these classes.

      Specification

      Specdiff attached.

      Attachments

        Issue Links

          Activity

            People

              alanb Alan Bateman
              alanb Alan Bateman
              Ron Pressler
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: