From 450f5d90c2c85cb2b031bcf4a65c3b1467231977 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Mon, 18 Dec 2023 13:34:36 -0500 Subject: [PATCH] doc: add math/rand/v2 release notes Change-Id: If1922413ff948f9b8d8cebec6756b6870f38c162 Reviewed-on: https://go-review.googlesource.com/c/go/+/550777 Reviewed-by: David Chase LUCI-TryBot-Result: Go LUCI --- doc/go1.22.html | 109 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 79 insertions(+), 30 deletions(-) diff --git a/doc/go1.22.html b/doc/go1.22.html index 792ea655ac..3d63e99eeb 100644 --- a/doc/go1.22.html +++ b/doc/go1.22.html @@ -274,40 +274,89 @@ defer func() {

New math/rand/v2 package

-

- TODO: https://go.dev/cl/502495: math/rand/v2: start of new API; modified api/next/61716.txt -

- -

- TODO: https://go.dev/cl/502497: math/rand/v2: remove Read; modified api/next/61716.txt -

- -

- TODO: https://go.dev/cl/502498: math/rand/v2: remove Rand.Seed; modified api/next/61716.txt -

- -

- TODO: https://go.dev/cl/502499: math/rand/v2: change Source to use uint64; modified api/next/61716.txt -

- -

- TODO: https://go.dev/cl/502500: math/rand/v2: add, optimize N, UintN, Uint32N, Uint64N; modified api/next/61716.txt -

- -

- TODO: https://go.dev/cl/502505: math/rand/v2: add PCG-DXSM; modified api/next/61716.txt -

+ + + + + + + + + -

- TODO: https://go.dev/cl/502506: math/rand/v2: delete Mitchell/Reeds source; modified api/next/61716.txt +

+ Go 1.22 includes the first “v2” package in the standard library, + math/rand/v2. + The changes compared to math/rand are + detailed in proposal #61716. The most important changes are:

-

- TODO: https://go.dev/cl/516857: math/rand/v2: rename various functions; modified api/next/61716.txt -

+
    +
  • The Read method, deprecated in math/rand, +was not carried forward for math/rand/v2. +(It remains available in math/rand.) +The vast majority of calls to Read should use +crypto/rand’s Read instead. +Otherwise a custom Read can be constructed using the Uint64 method. + +
  • The global generator accessed by top-level functions is unconditionally randomly seeded. +Because the API guarantees no fixed sequence of results, +optimizations like per-thread random generator states are now possible. + +
  • The Source +interface now has a single Uint64 method; +there is no Source64 interface. + +
  • Many methods now use faster algorithms that were not possible to adopt in math/rand +because they changed the output streams. + +
  • The +Intn, +Int31, +Int31n, +Int63, +and +Int64n +top-level functions and methods from math/rand +are spelled more idiomatically in math/rand/v2: +IntN, +Int32, +Int32N, +Int64, +and +Int64N. +There are also new top-level functions and methods +Uint32, +Uint32N, +Uint64, +Uint64N, +Uint, +and +UintN. + +
  • The +new generic function N +is like +Int64N or +Uint64N +but works for any integer type. +For example a random duration from 0 up to 5 minutes is +rand.N(5*time.Minute). + +
  • The Mitchell & Reeds LFSR generator provided by +math/rand’s Source +has been replaced by two more modern pseudo-random generator sources: +ChaCha8 +PCG. +ChaCha8 is a new, cryptographically strong random number generator +roughly similar to PCG in efficiency. +ChaCha8 is the algorithm used for the top-level functions in math/rand/v2. +As of Go 1.22, math/rand's top-level functions (when not explicitly seeded) +and the Go runtime also use ChaCha8 for randomness. +
-

- TODO: https://go.dev/cl/516859: math/rand/v2: add ChaCha8; modified api/next/61716.txt +

+We plan to include an API migration tool in a future release, likely Go 1.23.

Minor changes to the library

-- 2.48.1