diff options
author | Russ Cox <rsc@golang.org> | 2023-12-18 13:34:36 -0500 |
---|---|---|
committer | Russ Cox <rsc@golang.org> | 2023-12-18 20:06:05 +0000 |
commit | 450f5d90c2c85cb2b031bcf4a65c3b1467231977 (patch) | |
tree | e9f3edef2c9d0a26725f402f50f848e3661899db | |
parent | 08bec0db3970319ef868b3c11d6cc077cab408b1 (diff) | |
download | go-450f5d90c2c85cb2b031bcf4a65c3b1467231977.tar.gz go-450f5d90c2c85cb2b031bcf4a65c3b1467231977.zip |
doc: add math/rand/v2 release notes
Change-Id: If1922413ff948f9b8d8cebec6756b6870f38c162
Reviewed-on: https://go-review.googlesource.com/c/go/+/550777
Reviewed-by: David Chase <drchase@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
-rw-r--r-- | doc/go1.22.html | 109 |
1 files 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() { <h3 id="math_rand_v2">New math/rand/v2 package</h3> -<p><!-- CL 502495 --> - TODO: <a href="https://go.dev/cl/502495">https://go.dev/cl/502495</a>: math/rand/v2: start of new API; modified api/next/61716.txt -</p> - -<p><!-- CL 502497 --> - TODO: <a href="https://go.dev/cl/502497">https://go.dev/cl/502497</a>: math/rand/v2: remove Read; modified api/next/61716.txt -</p> - -<p><!-- CL 502498 --> - TODO: <a href="https://go.dev/cl/502498">https://go.dev/cl/502498</a>: math/rand/v2: remove Rand.Seed; modified api/next/61716.txt -</p> - -<p><!-- CL 502499 --> - TODO: <a href="https://go.dev/cl/502499">https://go.dev/cl/502499</a>: math/rand/v2: change Source to use uint64; modified api/next/61716.txt -</p> - -<p><!-- CL 502500 --> - TODO: <a href="https://go.dev/cl/502500">https://go.dev/cl/502500</a>: math/rand/v2: add, optimize N, UintN, Uint32N, Uint64N; modified api/next/61716.txt -</p> - -<p><!-- CL 502505 --> - TODO: <a href="https://go.dev/cl/502505">https://go.dev/cl/502505</a>: math/rand/v2: add PCG-DXSM; modified api/next/61716.txt -</p> +<!-- CL 502495 --> +<!-- CL 502497 --> +<!-- CL 502498 --> +<!-- CL 502499 --> +<!-- CL 502500 --> +<!-- CL 502505 --> +<!-- CL 502506 --> +<!-- CL 516857 --> +<!-- CL 516859 --> -<p><!-- CL 502506 --> - TODO: <a href="https://go.dev/cl/502506">https://go.dev/cl/502506</a>: math/rand/v2: delete Mitchell/Reeds source; modified api/next/61716.txt +<p> + Go 1.22 includes the first “v2” package in the standard library, + <a href="/pkg/math/rand/v2/"><code>math/rand/v2</code></a>. + The changes compared to <a href="/pkg/math/rand/"><code>math/rand</code></a> are + detailed in <a href="/issue/61716">proposal #61716</a>. The most important changes are: </p> -<p><!-- CL 516857 --> - TODO: <a href="https://go.dev/cl/516857">https://go.dev/cl/516857</a>: math/rand/v2: rename various functions; modified api/next/61716.txt -</p> +<ul> +<li>The <code>Read</code> method, deprecated in <code>math/rand</code>, +was not carried forward for <code>math/rand/v2</code>. +(It remains available in <code>math/rand</code>.) +The vast majority of calls to <code>Read</code> should use +<a href="/pkg/crypto/rand/#Read"><code>crypto/rand</code>’s <code>Read</code></a> instead. +Otherwise a custom <code>Read</code> can be constructed using the <code>Uint64</code> method. + +<li>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. + +<li>The <a href="/pkg/math/rand/v2/#Source"><code>Source</code></a> +interface now has a single <code>Uint64</code> method; +there is no <code>Source64</code> interface. + +<li>Many methods now use faster algorithms that were not possible to adopt in <code>math/rand</code> +because they changed the output streams. + +<li>The +<code>Intn</code>, +<code>Int31</code>, +<code>Int31n</code>, +<code>Int63</code>, +and +<code>Int64n</code> +top-level functions and methods from <code>math/rand</code> +are spelled more idiomatically in <code>math/rand/v2</code>: +<code>IntN</code>, +<code>Int32</code>, +<code>Int32N</code>, +<code>Int64</code>, +and +<code>Int64N</code>. +There are also new top-level functions and methods +<code>Uint32</code>, +<code>Uint32N</code>, +<code>Uint64</code>, +<code>Uint64N</code>, +<code>Uint</code>, +and +<code>UintN</code>. + +<li>The +new generic function <a href="/pkg/math/rand/v2/#N"><code>N</code></a> +is like +<a href="/pkg/math/rand/v2/#Int64N"><code>Int64N</code></a> or +<a href="/pkg/math/rand/v2/#Uint64N"><code>Uint64N</code></a> +but works for any integer type. +For example a random duration from 0 up to 5 minutes is +<code>rand.N(5*time.Minute)</code>. + +<li>The Mitchell & Reeds LFSR generator provided by +<a href="/pkg/math/rand/#Source"><code>math/rand</code>’s <code>Source</code></a> +has been replaced by two more modern pseudo-random generator sources: +<a href="/pkg/math/rand/v2/#ChaCha8"><code>ChaCha8</code></a> +<a href="/pkg/math/rand/v2/#PCG"><code>PCG</code></a>. +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 <code>math/rand/v2</code>. +As of Go 1.22, <code>math/rand</code>'s top-level functions (when not explicitly seeded) +and the Go runtime also use ChaCha8 for randomness. +</ul> -<p><!-- CL 516859 --> - TODO: <a href="https://go.dev/cl/516859">https://go.dev/cl/516859</a>: math/rand/v2: add ChaCha8; modified api/next/61716.txt +<p> +We plan to include an API migration tool in a future release, likely Go 1.23. </p> <h3 id="minor_library_changes">Minor changes to the library</h3> |