luci: go.chromium.org/luci/common/data/rand/mathrand Index | Files

package mathrand

import "go.chromium.org/luci/common/data/rand/mathrand"

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

Package Files

impl.go mathrand.go seed.go

func ExpFloat64 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 hte 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 Uses

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 mathrand imports 5 packages (graph) and is imported by 55 packages. Updated 2018-08-19. Refresh now. Tools for package owners.