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

Documentation suggests there are ArbitrarilyJumpableGenerator when none

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 18
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      source
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Hide
      No net effect.
      Show
      No net effect.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      "Xoroshiro128PlusPlus", and "Xoshiro256PlusPlus" are incorrectly stated as being RandomGenerator.ArbitrarilyJumpableGenerator.

      Problem

      "There is also an interface RandomGenerator.ArbitrarilyJumpableGenerator for algorithms that allow jumping along the state cycle by any user-specified distance. In this package, implementations of these interfaces include "Xoroshiro128PlusPlus", and "Xoshiro256PlusPlus" is incorrect. "Xoroshiro128PlusPlus", and "Xoshiro256PlusPlus" are actually RandomGenerator.JumpableGenerator.

      Solution

      Correct the documentation.

      Specification

      diff --git a/src/java.base/share/classes/java/util/random/package-info.java b/src/java.base/share/classes/java/util/random/package-info.java
      index 8efaa0bd4c3..102410bffe6 100644
      --- a/src/java.base/share/classes/java/util/random/package-info.java
      +++ b/src/java.base/share/classes/java/util/random/package-info.java
      @@ -347,12 +347,12 @@
        * supported by the interface {@link RandomGenerator.JumpableGenerator}.
        * Sometimes it is desirable to support two levels of jumping (by long distances
        * and by <i>really</i> long distances); this strategy is supported by the
      - * interface {@link RandomGenerator.LeapableGenerator}. There is also an interface
      + * interface {@link RandomGenerator.LeapableGenerator}. In this package,
      + * implementations of this interface include "Xoroshiro128PlusPlus" and
      + * "Xoshiro256PlusPlus". There is also an interface
        * {@link RandomGenerator.ArbitrarilyJumpableGenerator} for algorithms that allow
      - * jumping along the state cycle by any user-specified distance. In this package,
      - * implementations of these interfaces include
      - * "Xoroshiro128PlusPlus", and
      - * "Xoshiro256PlusPlus".
      + * jumping along the state cycle by any user-specified distance; there are currently
      + * no implementations of this interface in this package.
        *
        * <p> A more recent category of "splittable" pseudorandom generator algorithms
        * uses a large family of state cycles and makes some attempt to ensure that
      @@ -382,13 +382,18 @@
        * equidistribution, scalability, and better quality.  Each of the
        * specific implementations here combines one of the best currently known
        * XBG algorithms (xoroshiro128 or xoshiro256, described by Blackman and
      - * Vigna in "Scrambled Linear Pseudorandom Number Generators", ACM Transactions
      - * on Mathematical Software, 2021) with an LCG that uses one of the best
      + * Vigna in "Scrambled Linear Pseudorandom Number Generators", <i>ACM Transactions
      + * on Mathematical Software</i>, 2021) with an LCG that uses one of the best
        * currently known multipliers (found by a search for better multipliers
      - * in 2019 by Steele and Vigna), and then applies either a mixing function
      - * identified by Doug Lea or a simple scrambler proposed by Blackman and Vigna.
      - * Testing has confirmed that the LXM algorithm is far superior in quality to
      - * the SplitMix algorithm (2014) used by {@code SplittableRandom}.
      + * in 2019 by Steele and Vigna, described in "Computationally Easy, Spectrally
      + * Good Multipliers for Congruential Pseudorandom Number Generators",
      + * <i>Software: Practice and Experience</i> (2021), doi:10.1002/spe.3030),
      + * and then applies either a mixing function identified by Doug Lea or
      + * or a simple scrambler proposed by Blackman and Vigna. Testing has
      + * confirmed that the LXM algorithm is far superior in quality to the
      + * SplitMix algorithm (2014) used by {@code SplittableRandom}
      + * (see Steele and Vigna, "LXM: Better Splittable Pseudorandom Number
      + * Generators (and Almost as Fast)", <i>Proc. 2021 ACM OOPSLA Conference</i>).
        *
        * Each class with a name of the form
        * {@code L}<i>p</i>{@code X}<i>q</i>{@code SomethingRandom}

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              gls Guy Steele
              Reporter:
              webbuggrp Webbug Group
              Reviewed By:
              Roger Riggs
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: