fastrand

README

fastrand

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

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

The generator passes the SmallCrush suite, part of TestU01 framework: http://simul.iro.umontreal.ca/testu01/tu01.html

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.18 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 ± 0%   3.4ns ±49%  -68.34%  (p=0.008 n=5+5)
SingleCore/Uint64()-16      11.3ns ± 0%   5.0ns ± 0%  -55.36%  (p=0.000 n=5+4)
SingleCore/Int()-16         10.8ns ± 0%   6.4ns ±14%  -40.18%  (p=0.008 n=5+5)
SingleCore/Intn(32)-16      11.9ns ± 0%   4.2ns ± 0%  -64.81%  (p=0.029 n=4+4)
SingleCore/Read/1024-16      701ns ± 0%   159ns ± 1%  -77.30%  (p=0.008 n=5+5)
SingleCore/Read/10240-16    6.84µs ± 0%  1.45µs ± 0%  -78.87%  (p=0.016 n=4+5)
SingleCore/Perm/1024-16     24.7µs ± 2%  11.1µs ± 1%  -54.93%  (p=0.008 n=5+5)
SingleCore/Shuffle/1024-16  12.1µs ± 0%   5.3µs ± 1%  -56.40%  (p=0.008 n=5+5)
MultipleCore/Uint32()-16     124ns ± 4%     0ns ± 1%  -99.85%  (p=0.008 n=5+5)
MultipleCore/Uint64()-16     127ns ± 6%     0ns ± 1%  -99.67%  (p=0.008 n=5+5)
MultipleCore/Int()-16        128ns ± 3%     1ns ± 1%  -99.57%  (p=0.008 n=5+5)
MultipleCore/Intn(32)-16     127ns ± 3%     0ns ± 1%  -99.65%  (p=0.008 n=5+5)
MultipleCore/Read/1024-16   1.13µs ± 2%  0.10µs ± 0%  -91.29%  (p=0.008 n=5+5)
MultipleCore/Read/10240-16  10.3µs ± 6%   0.6µs ± 0%  -94.25%  (p=0.008 n=5+5)
MultipleCore/Perm/1024-16    208µs ± 1%     3µs ± 3%  -98.60%  (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 Uint64() uint64
• func Uint64n(n uint64) uint64

Variables

var Uint32 = runtimefastrand

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

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 Uint64

func Uint64() uint64

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

func Uint64n

func Uint64n(n uint64) uint64

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