fastrand

README

fastrand

As of Go1.22, the fastrand is just a wrapper of math/rand/v2, please use the standard library instead.

The fastrand is developed from the background that math/rand is unscalable. Because math/rand and math/rand/v2 become scalable since Go1.22, there is no need to use this library.

fastrand is the fastest pseudo-random number generator in Go. Support most common APIs of math/rand.

This generator base on the Go runtime per-M structure, and the init-seed provided by the Go runtime, which means you can't add your seed, but these methods scale very well on multiple cores.

Compare to math/rand

• 2 ~ 200x faster
• Scales well on multiple cores
• Not provide a stable value stream (can't inject init-seed)
• Fix bugs in math/rand Float64 and Float32 (since no need to preserve the value stream)

Benchmark

Go version: go1.19 linux/amd64

CPU: AMD 3700x(8C16T), running at 3.6GHz

OS: ubuntu 18.04

MEMORY: 16G x 2 (3200MHz)

name                        old time/op  new time/op  delta
SingleCore/Uint32()-16      10.7ns ± 1%   2.3ns ± 1%  -78.58%  (p=0.008 n=5+5)
SingleCore/Uint64()-16      11.3ns ± 1%   2.3ns ± 0%  -79.59%  (p=0.008 n=5+5)
SingleCore/Int()-16         10.9ns ± 2%   3.6ns ± 0%  -66.89%  (p=0.016 n=5+4)
SingleCore/Intn(32)-16      12.0ns ± 2%   4.2ns ± 2%  -64.74%  (p=0.016 n=5+4)
SingleCore/Read/1024-16      937ns ± 2%   157ns ± 2%  -83.30%  (p=0.008 n=5+5)
SingleCore/Read/10240-16    9.29µs ± 2%  1.82µs ±60%  -80.42%  (p=0.008 n=5+5)
SingleCore/Perm/1024-16     23.9µs ± 1%   9.2µs ± 2%  -61.42%  (p=0.008 n=5+5)
SingleCore/Shuffle/1024-16  12.3µs ± 0%   5.4µs ± 1%  -56.34%  (p=0.008 n=5+5)
MultipleCore/Uint32()-16     146ns ±11%     0ns ± 2%  -99.87%  (p=0.008 n=5+5)
MultipleCore/Uint64()-16     151ns ± 4%     0ns ± 1%  -99.86%  (p=0.008 n=5+5)
MultipleCore/Int()-16        148ns ± 4%     0ns ± 1%  -99.79%  (p=0.008 n=5+5)
MultipleCore/Intn(32)-16     154ns ± 8%     0ns ± 1%  -99.71%  (p=0.008 n=5+5)
MultipleCore/Read/1024-16   1.64µs ± 6%  0.10µs ± 1%  -94.04%  (p=0.008 n=5+5)
MultipleCore/Read/10240-16  15.5µs ± 5%   0.6µs ± 1%  -96.20%  (p=0.008 n=5+5)
MultipleCore/Perm/1024-16    233µs ± 6%     2µs ± 6%  -99.01%  (p=0.008 n=5+5)

Documentation

Overview

Package fastrand is the fastest pseudorandom number generator in Go(multiple-cores).

Index

• Variables
• func Float32() float32
• func Float64() float64
• func Int() int
• func Int31() int32
• func Int31n(n int32) int32
• func Int63() int64
• func Int63n(n int64) int64
• func Intn(n int) int
• func Perm(n int) []int
• func Read(p []byte) (int, error)
• func Shuffle(n int, swap func(i, j int))
• func Uint32n(n uint32) uint32
• func Uint64n(n uint64) uint64
• func Uintn(n uint) uint

Variables

var Uint = runtimefastrandu

Uint returns a pseudo-random 32-bit or 64-bit value.

var Uint32 = runtimefastrand

Uint32 returns a pseudo-random 32-bit value as a uint32.

var Uint64 = runtimefastrand64

Uint64 returns a pseudo-random 64-bit value as a uint64.

Functions

func Float32

func Float32() float32

func Float64

func Float64() float64

func Int

func Int() int

Int returns a non-negative pseudo-random int.

func Int31

func Int31() int32

Int31 returns a non-negative pseudo-random 31-bit integer as an int32.

func Int31n

func Int31n(n int32) int32

Int31n returns, as an int32, a non-negative pseudo-random number in [0,n). It panics if n <= 0. For implementation details, see: https://lemire.me/blog/2016/06/27/a-fast-alternative-to-the-modulo-reduction

func Int63

func Int63() int64

Int63 returns a non-negative pseudo-random 63-bit integer as an int64.

func Int63n

func Int63n(n int64) int64

Int63n returns, as an int64, a non-negative pseudo-random number in [0,n). It panics if n <= 0.

func Intn

func Intn(n int) int

Intn returns, as an int, a non-negative pseudo-random number in [0,n). It panics if n <= 0.

func Perm

func Perm(n int) []int

Perm returns, as a slice of n ints, a pseudo-random permutation of the integers in the half-open interval [0,n).

func Read

func Read(p []byte) (int, error)

Read generates len(p) random bytes and writes them into p. It always returns len(p) and a nil error. It is safe for concurrent use.

func Shuffle

func Shuffle(n int, swap func(i, j int))

Shuffle pseudo-randomizes the order of elements. n is the number of elements. Shuffle panics if n < 0. swap swaps the elements with indexes i and j.

func Uint32n

func Uint32n(n uint32) uint32

Uint32n returns a pseudo-random number in [0,n).

func Uint64n

func Uint64n(n uint64) uint64

Uint64n returns a pseudo-random number in [0,n).

func Uintn

func Uintn(n uint) uint

Uintn returns a pseudo-random number in [0,n).