randjump: deprecate the array version?

NEWS.md

@@ -1228,6 +1228,9 @@ Deprecated or removed
   * `rand(t::Tuple{Vararg{Int}})` is deprecated in favor of `rand(Float64, t)` or `rand(t...)`;
     `rand(::Tuple)` will have another meaning in the future ([#25429], [#25278]).
 
+  * `randjump`, which produced an array, is deprecated in favor of the
+    scalar version `Future.randjump` used with `accumulate` ([#27746]).
+
   * The `assert` function (and `@assert` macro) have been documented that they are not guaranteed to run under various optimization levels and should therefore not be used to e.g. verify passwords.
 
   * `ObjectIdDict` has been deprecated in favor of `IdDict{Any,Any}` ([#25210]).

doc/src/manual/parallel-computing.md

@@ -1576,11 +1576,11 @@ creates separate instances of `Regex` object for each entry of `rx` vector.
 
 The case of `rand` is a bit more complex as we have to ensure that each thread
 uses non-overlapping pseudorandom number sequences. This can be simply ensured
-by using [`randjump`](@ref) function:
+by using the `Future.randjump` function:
 
 
 ```julia-repl
-julia> using Random
+julia> using Random; import Future
 
 julia> function g_fix(r)
            a = zeros(1000)
@@ -1591,7 +1591,10 @@ julia> function g_fix(r)
        end
 g_fix (generic function with 1 method)
 
-julia> r = randjump(MersenneTwister(1), big(10)^20, nthreads());
+julia>  r = let m = MersenneTwister(1)
+                [m; accumulate(Future.randjump, m, fill(big(10)^20, nthreads()-1))]
+            end;
+
 julia> g_fix(r)
 1000
 ```

stdlib/Random/docs/src/index.md

@@ -34,7 +34,6 @@ Random.randn
 Random.randn!
 Random.randexp
 Random.randexp!
-Random.randjump
 Random.randstring
 Random.randsubseq
 Random.randsubseq!

stdlib/Random/src/RNGs.jl

@@ -555,30 +555,7 @@ end
 
 ### randjump
 
-"""
-    randjump(r::MersenneTwister, steps::Integer, len::Integer) -> Vector{MersenneTwister}
-
-Create an array of size `len` of initialized `MersenneTwister` RNG objects. The
-first RNG object given as a parameter and following `MersenneTwister` RNGs in the array are
-initialized such that a state of the RNG object in the array would be moved forward (without
-generating numbers) from a previous RNG object array element by `steps` steps.
-One such step corresponds to the generation of two `Float64` numbers.
-For each different value of `steps`, a large polynomial has to be generated internally.
-One is already pre-computed for `steps=big(10)^20`.
-"""
-randjump(r::MersenneTwister, steps::Integer, len::Integer) =
-    _randjump(r, DSFMT.calc_jump(steps), len)
-
+# Old randjump methods are deprecated, the scalar version is in the Future module.
 
 _randjump(r::MersenneTwister, jumppoly::DSFMT.GF2X) =
     fillcache_zeros!(MersenneTwister(copy(r.seed), DSFMT.dsfmt_jump(r.state, jumppoly)))
-
-function _randjump(mt::MersenneTwister, jumppoly::DSFMT.GF2X, len::Integer)
-    mts = MersenneTwister[]
-    push!(mts, mt)
-    for i in 1:len-1
-        cmt = mts[end]
-        push!(mts, _randjump(cmt, jumppoly))
-    end
-    return mts
-end

stdlib/Random/src/deprecated.jl

@@ -10,12 +10,27 @@ Base.@deprecate_binding dSFMT DSFMT
 @deprecate MersenneTwister(filename::AbstractString)  srand(MersenneTwister(0), read!(filename, Vector{UInt32}(undef, Int(4))))
 
 function randjump(mt::MersenneTwister, jumps::Integer, jumppoly::AbstractString)
-    depwarn("`randjump(rng, jumps, jumppoly::AbstractString)` is deprecated; use `randjump(rng, steps, jumps)` instead", :randjump)
-    Base.Random._randjump(mt, DSFMT.GF2X(jumppoly), jumps)
+    Base.depwarn("`randjump(rng, jumps, [jumppoly::AbstractString])` is deprecated; use `Future.randjump` and `accumulate` instead", :randjump)
+    _randjump(mt, DSFMT.GF2X(jumppoly), jumps)
 end
 
 @deprecate randjump(mt::MersenneTwister, jumps::Integer)  randjump(mt, big(10)^20, jumps)
 
+function randjump(r::MersenneTwister, steps::Integer, len::Integer)
+    Base.depwarn("`randjump(rng, steps::Integer, len::Integer` is deprecated; use `Future.randjump` and `accumulate` instead", :randjump)
+    _randjump(r, DSFMT.calc_jump(steps), len)
+end
+
+function _randjump(mt::MersenneTwister, jumppoly::DSFMT.GF2X, len::Integer)
+    mts = MersenneTwister[]
+    push!(mts, mt)
+    for i in 1:len-1
+        cmt = mts[end]
+        push!(mts, _randjump(cmt, jumppoly))
+    end
+    return mts
+end
+
 # PR #25429
 @deprecate rand(r::AbstractRNG, dims::Dims) rand(r, Float64, dims)
 @deprecate rand(                dims::Dims) rand(Float64, dims)

stdlib/Random/test/runtests.jl

@@ -11,6 +11,8 @@ using Random.DSFMT
 
 using Random: Sampler, SamplerRangeFast, SamplerRangeInt, MT_CACHE_F, MT_CACHE_I
 
+import Future # randjump
+
 @testset "Issue #6573" begin
     srand(0)
     rand()
@@ -514,7 +516,13 @@ end
 
     # test PRNG jump
 
-    mts = randjump(mta, 25000, size)
+    function randjumpvec(m, steps, len) # old version of randjump
+        mts = accumulate(Future.randjump, m, fill(steps, len-1))
+        pushfirst!(mts, m)
+        mts
+    end
+
+    mts = randjumpvec(mta, 25000, size)
     @test length(mts) == 4
 
     for x in (rand(mts[k], Float64) for j=1:step, k=1:size)
@@ -523,7 +531,7 @@ end
 
     @testset "generated RNGs are in a deterministic state (relatively to ==)" begin
         m = MersenneTwister()
-        @test randjump(m, 25000, 2) == randjump(m, 25000, 2)
+        @test Future.randjump(m, 25000) == Future.randjump(m, 25000)
     end
 end
 
@@ -573,10 +581,10 @@ let seed = rand(UInt32, 10)
     r = MersenneTwister(seed)
     @test r.seed == seed && r.seed !== seed
     # RNGs do not share their seed in randjump
-    let rs = randjump(r, big(10)^20, 2)
-        @test  rs[1].seed !== rs[2].seed
-        srand(rs[2])
-        @test seed == rs[1].seed != rs[2].seed
+    let r2 = Future.randjump(r, big(10)^20)
+        @test  r.seed !== r2.seed
+        srand(r2)
+        @test seed == r.seed != r2.seed
     end
     resize!(seed, 4)
     @test r.seed != seed