From 737ee7a016d606e4b33e0654d9f93bcdd06c7cc7 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Tue, 15 Jul 2025 09:08:35 -0700 Subject: [PATCH] Remove Preview1's advice about random-number generators. Previously, the preview1 documentation for the `random_get` function said: > This function may execute slowly, so when large mounts of random data are > required, it's advisable to use this function to seed a pseudo-random > number generator, rather than to provide the random data directly. However, Wasm guest code is unaware of VM forks in any VMs might be running in, as well as snapshot/resume features offered by some Wasm engines and tools, so in practice, WASI use cases have tended toward using `random_get` in place of guest PRNGs, and thus to relying on `random_get` executing quickly. This pattern seems sufficiently widely applicable to motivate updating WASIp1 to reflect it. To be sure, this is not a behavior change; it's just removing what we now understand to be bad advice in general. WASIp2 for its part has already made a similar change. --- legacy/preview0/docs.md | 3 --- legacy/preview0/witx/wasi_unstable.witx | 3 --- legacy/preview1/docs.html | 2 +- legacy/preview1/docs.md | 3 --- legacy/preview1/witx/wasi_snapshot_preview1.witx | 3 --- 5 files changed, 1 insertion(+), 13 deletions(-) diff --git a/legacy/preview0/docs.md b/legacy/preview0/docs.md index 634e304b..7603446c 100644 --- a/legacy/preview0/docs.md +++ b/legacy/preview0/docs.md @@ -2394,9 +2394,6 @@ Note: This is similar to [`sched_yield`](#sched_yield) in POSIX. Write high-quality random data into a buffer. This function blocks when the implementation is unable to immediately provide sufficient high-quality random data. -This function may execute slowly, so when large mounts of random data are -required, it's advisable to use this function to seed a pseudo-random -number generator, rather than to provide the random data directly. ##### Params - `buf`: `Pointer` diff --git a/legacy/preview0/witx/wasi_unstable.witx b/legacy/preview0/witx/wasi_unstable.witx index ee01abcf..96f5953d 100644 --- a/legacy/preview0/witx/wasi_unstable.witx +++ b/legacy/preview0/witx/wasi_unstable.witx @@ -466,9 +466,6 @@ ;;; Write high-quality random data into a buffer. ;;; This function blocks when the implementation is unable to immediately ;;; provide sufficient high-quality random data. - ;;; This function may execute slowly, so when large mounts of random data are - ;;; required, it's advisable to use this function to seed a pseudo-random - ;;; number generator, rather than to provide the random data directly. (@interface func (export "random_get") ;;; The buffer to fill with random data. (param $buf (@witx pointer u8)) diff --git a/legacy/preview1/docs.html b/legacy/preview1/docs.html index 2419ff3d..73528db3 100644 --- a/legacy/preview1/docs.html +++ b/legacy/preview1/docs.html @@ -1211,7 +1211,7 @@
Results

<a href="#random_get" name="random_get"></a> random_get(buf: Pointer<u8>, buf_len: size) -> errno

-

Write high-quality random data into a buffer.
This function blocks when the implementation is unable to immediately
provide sufficient high-quality random data.
This function may execute slowly, so when large mounts of random data are
required, it's advisable to use this function to seed a pseudo-random
number generator, rather than to provide the random data directly.

+

Write high-quality random data into a buffer.
This function blocks when the implementation is unable to immediately
provide sufficient high-quality random data.

Params