Back to godoc.org

Package mathrand

v0.0.0-...-d4769a7
Latest Go to latest

The latest major version is .

Published: Aug 1, 2020 | License: Apache-2.0 | Module: github.com/luci/luci-go

Overview

Package mathrand implements a mockable interface for math/rand.Rand.

It is controllable through context.Context. You should use this instead of math/rand directly, to allow you to make deterministic tests.

Index

func ExpFloat64

func ExpFloat64(c context.Context) float64

ExpFloat64 returns an exponentially distributed float64 in the range (0, +math.MaxFloat64] with an exponential distribution whose rate parameter (lambda) is 1 and whose mean is 1/lambda (1) from the source in the context or the shared global source.

To produce a distribution with a different rate parameter, callers can adjust the output using:

sample = ExpFloat64(ctx) / desiredRateParameter

func Float32

func Float32(c context.Context) float32

Float32 returns, as a float32, a pseudo-random number in [0.0,1.0) from the source in the context or the shared global source.

func Float64

func Float64(c context.Context) float64

Float64 returns, as a float64, a pseudo-random number in [0.0,1.0) from the source in the context or the shared global source.

func Int

func Int(c context.Context) int

Int returns a non-negative pseudo-random int from the source in the context or the shared global source.

func Int31

func Int31(c context.Context) int32

Int31 returns a non-negative pseudo-random 31-bit integer as an int32 from the source in the context or the shared global source.

func Int31n

func Int31n(c context.Context, n int32) int32

Int31n returns, as an int32, a non-negative pseudo-random number in [0,n) from the source in the context or the shared global source.

It panics if n <= 0.

func Int63

func Int63(c context.Context) int64

Int63 returns a non-negative pseudo-random 63-bit integer as an int64 from the source in the context or the shared global source.

func Int63n

func Int63n(c context.Context, n int64) int64

Int63n returns, as an int64, a non-negative pseudo-random number in [0,n) from the source in the context or the shared global source.

It panics if n <= 0.

func Intn

func Intn(c context.Context, n int) int

Intn returns, as an int, a non-negative pseudo-random number in [0,n) from the source in the context or the shared global source.

It panics if n <= 0.

func NormFloat64

func NormFloat64(c context.Context) float64

NormFloat64 returns a normally distributed float64 in the range [-math.MaxFloat64, +math.MaxFloat64] with standard normal distribution (mean = 0, stddev = 1) from the source in the context or the shared global source.

To produce a different normal distribution, callers can adjust the output using:

sample = NormFloat64(ctx) * desiredStdDev + desiredMean

func Perm

func Perm(c context.Context, n int) []int

Perm returns, as a slice of n ints, a pseudo-random permutation of the integers [0,n) from the source in the context or the shared global source.

func Read

func Read(c context.Context, p []byte) (n int, err error)

Read generates len(p) random bytes from the source in the context or the shared global source and writes them into p. It always returns len(p) and a nil error.

func SeedRandomly

func SeedRandomly()

SeedRandomly seeds global math/rand RNG with bytes from crypto-random source.

It is a good idea to call this in main() of some process to guarantee that multiple instances of this process don't go through the exact same PRNG sequence (go runtime doesn't seed math/rand itself).

func Set

func Set(c context.Context, mr *rand.Rand) context.Context

Set sets the current *"math/rand".Rand object in the context.

Useful for testing with a quick mock. The supplied *rand.Rand will be wrapped in a *Locking if necessary such that when it is returned from Get, it is safe for concurrent use.

func SetRand

func SetRand(c context.Context, r Rand) context.Context

SetRand sets the current Rand object in the context.

Useful for testing with a quick mock. The supplied Rand will be wrapped in a *Locking if necessary such that when it is returned from Get, it is safe for concurrent use.

func Uint32

func Uint32(c context.Context) uint32

Uint32 returns a pseudo-random 32-bit value as a uint32 from the source in the context or the shared global source.

func WithGoRand

func WithGoRand(c context.Context, fn func(r *rand.Rand) error) error

WithGoRand invokes the supplied "fn" while holding an exclusive lock for it. This can be used by callers to pull and use a *rand.Rand instance out of the Context safely.

The callback's r must not be retained or used outside of the scope of the callback.

type Locking

type Locking struct {
	sync.Mutex
	R Rand
}

Locking wraps a Rand instance in a layer that locks around all of its methods.

A user must hold Locking's Mutex if the want to directly access and use Locking's R member safely.

By default, a Rand instance is not safe for concurrent use. A ocking Rand instance is.

func (*Locking) ExpFloat64

func (l *Locking) ExpFloat64() (v float64)

ExpFloat64 returns an exponentially distributed float64 in the range (0, +math.MaxFloat64] with an exponential distribution whose rate parameter (lambda) is 1 and whose mean is 1/lambda (1) from the source in the context or the shared global source.

To produce a distribution with a different rate parameter, callers can adjust the output using:

sample = ExpFloat64(ctx) / desiredRateParameter

func (*Locking) Float32

func (l *Locking) Float32() (v float32)

Float32 returns, as a float32, a pseudo-random number in [0.0,1.0) from the source in the context or the shared global source.

func (*Locking) Float64

func (l *Locking) Float64() (v float64)

Float64 returns, as a float64, a pseudo-random number in [0.0,1.0) from the source in the context or the shared global source.

func (*Locking) Int

func (l *Locking) Int() (v int)

Int returns a non-negative pseudo-random int from the source in the context or the shared global source.

func (*Locking) Int31

func (l *Locking) Int31() (v int32)

Int31 returns a non-negative pseudo-random 31-bit integer as an int32 from the source in the context or the shared global source.

func (*Locking) Int31n

func (l *Locking) Int31n(n int32) (v int32)

Int31n returns, as an int32, a non-negative pseudo-random number in [0,n) from the source in the context or the shared global source.

It panics if n <= 0.

func (*Locking) Int63

func (l *Locking) Int63() (v int64)

Int63 returns a non-negative pseudo-random 63-bit integer as an int64 from the source in the context or the shared global source.

func (*Locking) Int63n

func (l *Locking) Int63n(n int64) (v int64)

Int63n returns, as an int64, a non-negative pseudo-random number in [0,n) from the source in the context or the shared global source.

It panics if n <= 0.

func (*Locking) Intn

func (l *Locking) Intn(n int) (v int)

Intn returns, as an int, a non-negative pseudo-random number in [0,n) from the source in the context or the shared global source.

It panics if n <= 0.

func (*Locking) NormFloat64

func (l *Locking) NormFloat64() (v float64)

NormFloat64 returns a normally distributed float64 in the range [-math.MaxFloat64, +math.MaxFloat64] with standard normal distribution (mean = 0, stddev = 1) from the source in the context or the shared global source.

To produce a different normal distribution, callers can adjust the output using:

sample = NormFloat64(ctx) * desiredStdDev + desiredMean

func (*Locking) Perm

func (l *Locking) Perm(n int) (v []int)

Perm returns, as a slice of n ints, a pseudo-random permutation of the integers [0,n) from the source in the context or the shared global source.

func (*Locking) Read

func (l *Locking) Read(p []byte) (n int, err error)

Read generates len(p) random bytes from the source in the context or the shared global source and writes them into p. It always returns len(p) and a nil error.

func (*Locking) Uint32

func (l *Locking) Uint32() (v uint32)

Uint32 returns a pseudo-random 32-bit value as a uint32 from the source in the context or the shared global source.

func (*Locking) WithGoRand

func (l *Locking) WithGoRand(fn func(r *rand.Rand) error) error

WithGoRand invokes the supplied "fn" while holding an exclusive lock for it. This can be used by callers to pull and use a *rand.Rand instance out of the Context safely.

The callback's r must not be retained or used outside of the scope of the callback.

type Rand

type Rand interface {
	// Int63 returns a non-negative pseudo-random 63-bit integer as an int64
	// from the source in the context or the shared global source.
	Int63() int64

	// Uint32 returns a pseudo-random 32-bit value as a uint32 from the source in
	// the context or the shared global source.
	Uint32() uint32

	// Int31 returns a non-negative pseudo-random 31-bit integer as an int32 from
	// the source in the context or the shared global source.
	Int31() int32

	// Int returns a non-negative pseudo-random int from the source in the context
	// or the shared global source.
	Int() int

	// Int63n returns, as an int64, a non-negative pseudo-random number in [0,n)
	// from the source in the context or the shared global source.
	//
	// It panics if n <= 0.
	Int63n(n int64) int64

	// Int31n returns, as an int32, a non-negative pseudo-random number in [0,n)
	// from the source in the context or the shared global source.
	//
	// It panics if n <= 0.
	Int31n(n int32) int32

	// Intn returns, as an int, a non-negative pseudo-random number in [0,n) from
	// the source in the context or the shared global source.
	//
	// It panics if n <= 0.
	Intn(n int) int

	// Float64 returns, as a float64, a pseudo-random number in [0.0,1.0) from
	// the source in the context or the shared global source.
	Float64() float64

	// Float32 returns, as a float32, a pseudo-random number in [0.0,1.0) from
	// the source in the context or the shared global source.
	Float32() float32

	// Perm returns, as a slice of n ints, a pseudo-random permutation of the
	// integers [0,n) from the source in the context or the shared global source.
	Perm(n int) []int

	// Read generates len(p) random bytes from the source in the context or
	// the shared global source and writes them into p. It always returns len(p)
	// and a nil error.
	Read(p []byte) (n int, err error)

	// NormFloat64 returns a normally distributed float64 in the range
	// [-math.MaxFloat64, +math.MaxFloat64] with standard normal distribution
	// (mean = 0, stddev = 1) from the source in the context or the shared global
	// source.
	//
	// To produce a different normal distribution, callers can adjust the output
	// using:
	//
	//  sample = NormFloat64(ctx) * desiredStdDev + desiredMean
	//
	NormFloat64() float64

	// ExpFloat64 returns an exponentially distributed float64 in the range
	// (0, +math.MaxFloat64] with an exponential distribution whose rate parameter
	// (lambda) is 1 and whose mean is 1/lambda (1) from the source in the context
	// or the shared global source.
	//
	// To produce a distribution with a different rate parameter, callers can adjust
	// the output using:
	//
	//  sample = ExpFloat64(ctx) / desiredRateParameter
	//
	ExpFloat64() float64

	// WithGoRand invokes the supplied "fn" while holding an exclusive lock
	// for it. This can be used by callers to pull and use a *rand.Rand instance
	// out of the Context safely.
	//
	// Other "mathrand" functions and objects MUST NOT BE USED inside the
	// callback, as WithGoRand holds the lock to the current Rand instance, so any
	// additional function call will deadlock.
	//
	// The callback's r must not be retained or used outside of the scope of the
	// callback.
	WithGoRand(fn func(r *rand.Rand) error) error
}

Rand is a random number generator interface.

A Rand instance is not necessarily safe for concurrent use. In order to ensure that it is, wrap it in Locking or obtain it from a method that provides this guarantee (e.g., Get).

All Rand functions MUST NOT PANIC. In particular, the Locking implementation relies on embedded methods not panicking in order to release its lock, and a panic will cause it to hold its lock indefinitely.

func Get

func Get(c context.Context) Rand

Get gets a Rand from the Context. The resulting Rand is safe for concurrent use.

If one hasn't been set, this will return a global Rand object backed by a shared rand.Rand singleton. Just like in "math/rand", rand.Seed can be called prior to using Get to set the seed used by this singleton.

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier