Documentation
¶
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(c context.Context) float64
- func Float32(c context.Context) float32
- func Float64(c context.Context) float64
- func Int(c context.Context) int
- func Int31(c context.Context) int32
- func Int31n(c context.Context, n int32) int32
- func Int63(c context.Context) int64
- func Int63n(c context.Context, n int64) int64
- func Intn(c context.Context, n int) int
- func NormFloat64(c context.Context) float64
- func Perm(c context.Context, n int) []int
- func Read(c context.Context, p []byte) (n int, err error)
- func SeedRandomly()
- func Set(c context.Context, mr *rand.Rand) context.Context
- func SetRand(c context.Context, r Rand) context.Context
- func Uint32(c context.Context) uint32
- func WithGoRand(c context.Context, fn func(r *rand.Rand) error) error
- type Locking
- func (l *Locking) ExpFloat64() (v float64)
- func (l *Locking) Float32() (v float32)
- func (l *Locking) Float64() (v float64)
- func (l *Locking) Int() (v int)
- func (l *Locking) Int31() (v int32)
- func (l *Locking) Int31n(n int32) (v int32)
- func (l *Locking) Int63() (v int64)
- func (l *Locking) Int63n(n int64) (v int64)
- func (l *Locking) Intn(n int) (v int)
- func (l *Locking) NormFloat64() (v float64)
- func (l *Locking) Perm(n int) (v []int)
- func (l *Locking) Read(p []byte) (n int, err error)
- func (l *Locking) Uint32() (v uint32)
- func (l *Locking) WithGoRand(fn func(r *rand.Rand) error) error
- type Rand
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExpFloat64 ¶
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 ¶
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 ¶
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 ¶
Int returns a non-negative pseudo-random int from the source in the context or the shared global source.
func Int31 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Uint32 returns a pseudo-random 32-bit value as a uint32 from the source in the context or the shared global source.
func WithGoRand ¶
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.
Types ¶
type Locking ¶
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 ¶
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 ¶
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 ¶
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 ¶
Int returns a non-negative pseudo-random int from the source in the context or the shared global source.
func (*Locking) Int31 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 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 ¶
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.
Source Files