random.rs - source
Description: Source of the Rust file `library/std/src/random.rs`.

#
std/
random.rs

    1//! Random value generation.
    2
    3#[unstable(feature = "random", issue = "130703")]
    4pub use core::random::*;
    5
    6use crate::sys::random as sys;
    7
    8/// The default random source.
    9///
    10/// This asks the system for random data suitable for cryptographic purposes
    11/// such as key generation. If security is a concern, consult the platform
    12/// documentation below for the specific guarantees your target provides.
    13///
    14/// The high quality of randomness provided by this source means it can be quite
    15/// slow on some targets. If you need a large quantity of random numbers and
    16/// security is not a concern,  consider using an alternative random number
    17/// generator (potentially seeded from this one).
    18///
    19/// # Underlying sources
    20///
    21/// Platform               | Source
    22/// -----------------------|---------------------------------------------------------------
    23/// Linux                  | [`getrandom`] or [`/dev/urandom`] after polling `/dev/random`
    24/// Windows                | [`ProcessPrng`](https://learn.microsoft.com/en-us/windows/win32/seccng/processprng)
    25/// Apple                  | `CCRandomGenerateBytes`
    26/// DragonFly              | [`arc4random_buf`](https://man.dragonflybsd.org/?command=arc4random)
    27/// ESP-IDF                | [`esp_fill_random`](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/random.html#_CPPv415esp_fill_randomPv6size_t)
    28/// FreeBSD                | [`arc4random_buf`](https://man.freebsd.org/cgi/man.cgi?query=arc4random)
    29/// Fuchsia                | [`cprng_draw`](https://fuchsia.dev/reference/syscalls/cprng_draw)
    30/// Haiku                  | `arc4random_buf`
    31/// Illumos                | [`arc4random_buf`](https://www.illumos.org/man/3C/arc4random)
    32/// NetBSD                 | [`arc4random_buf`](https://man.netbsd.org/arc4random.3)
    33/// OpenBSD                | [`arc4random_buf`](https://man.openbsd.org/arc4random.3)
    34/// Solaris                | [`arc4random_buf`](https://docs.oracle.com/cd/E88353_01/html/E37843/arc4random-3c.html)
    35/// Vita                   | `arc4random_buf`
    36/// Hermit                 | `read_entropy`
    37/// Horizon, Cygwin        | `getrandom`
    38/// AIX, Hurd, L4Re, QNX   | `/dev/urandom`
    39/// Redox                  | `/scheme/rand`
    40/// RTEMS                  | [`arc4random_buf`](https://docs.rtems.org/branches/master/bsp-howto/getentropy.html)
    41/// SGX                    | [`rdrand`](https://en.wikipedia.org/wiki/RDRAND)
    42/// SOLID                  | `SOLID_RNG_SampleRandomBytes`
    43/// TEEOS                  | `TEE_GenerateRandom`
    44/// UEFI                   | [`EFI_RNG_PROTOCOL`](https://uefi.org/specs/UEFI/2.10/37_Secure_Technologies.html#random-number-generator-protocol)
    45/// VxWorks                | `randABytes` after waiting for `randSecure` to become ready
    46/// WASI                   | [`random_get`](https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md#-random_getbuf-pointeru8-buf_len-size---result-errno)
    47/// ZKVM                   | `sys_rand`
    48///
    49/// Note that the sources used might change over time.
    50///
    51/// Consult the documentation for the underlying operations on your supported
    52/// targets to determine whether they provide any particular desired properties,
    53/// such as support for reseeding on VM fork operations.
    54///
    55/// [`getrandom`]: https://www.man7.org/linux/man-pages/man2/getrandom.2.html
    56/// [`/dev/urandom`]: https://www.man7.org/linux/man-pages/man4/random.4.html
    57#[derive(Default, Debug, Clone, Copy)]
    58#[unstable(feature = "random", issue = "130703")]
    59pub struct DefaultRandomSource;
    60
    61#[unstable(feature = "random", issue = "130703")]
    62impl RandomSource for DefaultRandomSource {
    63    fn fill_bytes(&mut self, bytes: &mut [u8]) {
    64        sys::fill_bytes(bytes)
    65    }
    66}
    67
    68/// Generates a random value from a distribution, using the default random source.
    69///
    70/// This is a convenience function for `dist.sample(&mut DefaultRandomSource)` and will sample
    71/// according to the same distribution as the underlying [`Distribution`] trait implementation. See
    72/// [`DefaultRandomSource`] for more information about how randomness is sourced.
    73///
    74/// # Examples
    75///
    76/// Generating a [version 4/variant 1 UUID] represented as text:
    77/// ```
    78/// #![feature(random)]
    79///
    80/// use std::random::random;
    81///
    82/// let bits: u128 = random(..);
    83/// let g1 = (bits >> 96) as u32;
    84/// let g2 = (bits >> 80) as u16;
    85/// let g3 = (0x4000 | (bits >> 64) & 0x0fff) as u16;
    86/// let g4 = (0x8000 | (bits >> 48) & 0x3fff) as u16;
    87/// let g5 = (bits & 0xffffffffffff) as u64;
    88/// let uuid = format!("{g1:08x}-{g2:04x}-{g3:04x}-{g4:04x}-{g5:012x}");
    89/// println!("{uuid}");
    90/// ```
    91///
    92/// [version 4/variant 1 UUID]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
    93#[unstable(feature = "random", issue = "130703")]
    94pub fn random<T>(dist: impl Distribution<T>) -> T {
    95    dist.sample(&mut DefaultRandomSource)
    96}