Further simplify Random.jump and improve its documentation

xavierleroy · xavierleroy · commit aa36f9101fd5 · 2021-10-19T17:30:19.000+02:00
As suggested by @jhjourdan, it's simpler to take a copy of the current default state then jump it.
diff --git a/stdlib/random.ml b/stdlib/random.ml
@@ -137,7 +137,7 @@ module State = struct
 
 end
 
-let default_origin =
+let default =
   State.make
     [| 0b001001000011111101101010100010;
        0b001000010110100011000010001101;
@@ -149,7 +149,6 @@ let default_origin =
        0b111010100110001110110001001110 |]
 (* These are the first 240 binary digits of the fractional part of pi,
    as eight 30-bit integers. *)
-let default = State.copy default_origin
 
 let bits () = State.bits default
 let int bound = State.int default bound
@@ -165,16 +164,14 @@ let nativebits () = State.nativebits default
 
 (* Seeding *)
 
-let full_init seed =
-  State.reinit default_origin seed;
-  State.assign default default_origin
-
+let full_init seed = State.reinit default seed
 let init seed = full_init [| seed |]
 let self_init () = full_init (random_seed())
 
 (* Generating a new independent state by jumping *)
 
-let jump () = State.jump default_origin; State.copy default_origin
+let jump () =
+  let st = State.copy default in State.jump default; st
 
 (* Manipulating the current state. *)
 
diff --git a/stdlib/random.mli b/stdlib/random.mli
@@ -137,11 +137,15 @@ val set_state : State.t -> unit
 (** Set the state of the generator used by the basic functions. *)
 
 val jump : unit -> State.t
-(** Return a fresh PRNG state that is obtained by "jumping" from the
-    initial state of the generator used by the default functions.
-    "Jumping", here, means advancing the state as if a great many numbers
-    (here, 2{^128} numbers) were drawn from this state.
-    The state returned by {!Random.jump} is statistically independent
-    from the state used by the default functions.
+(** Return a fresh PRNG state that is statistically independent
+    from the state of the generator used by the basic functions.
     Data can be drawn from both states, in any order, without risk of
-    correlation. *)
+    correlation.
+    Multiple calls to {!Random.jump} will return PRNG states that
+    are pairwise statistically independent.
+    This is implemented by returning a copy of the current state of the
+    generator used by the basic functions, then jumping this generator,
+    i.e. advancing it as if a great many numbers (here, 2{^128} numbers)
+    were drawn from this generator.
+*)
+
