mathrand

package
v0.0.0-...-1643519 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2024 License: Apache-2.0 Imports: 5 Imported by: 32

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

Constants

This section is empty.

Variables

This section is empty.

Functions

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.

Types

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

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.