fastrand

README

fastrand

Fastest pseudo-random number generator in Go.

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

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

pseudo-random paper: https://www.jstatsoft.org/article/view/v008i14/xorshift.pdf

fast-modulo-reduction: https://lemire.me/blog/2016/06/27/a-fast-alternative-to-the-modulo-reduction/

Compare to math/rand

• Much faster (~5x faster for single-core; ~200x faster for multiple-cores)
• 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)

Bencmark

Go version: go1.15.6 linux/amd64

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

OS: ubuntu 18.04

MEMORY: 16G x 2 (3200MHz)

multiple-cores

name                                 time/op
MultipleCore/math/rand-Int31n(5)-16   152ns ± 0%
MultipleCore/fast-rand-Int31n(5)-16  0.40ns ± 0%
MultipleCore/math/rand-Int63n(5)-16   167ns ± 0%
MultipleCore/fast-rand-Int63n(5)-16  3.04ns ± 0%
MultipleCore/math/rand-Float32()-16   143ns ± 0%
MultipleCore/fast-rand-Float32()-16  0.40ns ± 0%
MultipleCore/math/rand-Uint32()-16    133ns ± 0%
MultipleCore/fast-rand-Uint32()-16   0.23ns ± 0%
MultipleCore/math/rand-Uint64()-16    140ns ± 0%
MultipleCore/fast-rand-Uint64()-16   0.56ns ± 0%

single-core

name                               time/op
SingleCore/math/rand-Int31n(5)-16  15.5ns ± 0%
SingleCore/fast-rand-Int31n(5)-16  3.91ns ± 0%
SingleCore/math/rand-Int63n(5)-16  24.4ns ± 0%
SingleCore/fast-rand-Int63n(5)-16  24.4ns ± 0%
SingleCore/math/rand-Uint32()-16   10.9ns ± 0%
SingleCore/fast-rand-Uint32()-16   2.86ns ± 0%
SingleCore/math/rand-Uint64()-16   11.3ns ± 0%
SingleCore/fast-rand-Uint64()-16   5.88ns ± 0%

compare to other repo

(multiple-cores)

rand-1 -> this repo

rand-2 -> https://github.com/valyala/fastrand

name                         time/op
VS/fastrand-1-Uint32()-16    0.23ns ± 0%
VS/fastrand-2-Uint32()-16    3.04ns ±23%
VS/fastrand-1-Uint32n(5)-16  0.23ns ± 1%
VS/fastrand-2-Uint32n(5)-16  3.13ns ±32%

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 = runtimex.Fastrand

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).