pgregory.net/rand

pgregory.net/rand

pgregory.net/rand is a fast, high-quality alternative to Go's standard math/rand and golang.org/x/exp/rand packages.

Key Features:

• API Compatibility: It is compatible with all *rand.Rand methods and most top-level functions (except Seed()).
• Performance: Significantly faster than standard library alternatives.
• Improved Quality: Provides higher quality random number generation.
• Simplified Initialization: Uses a more direct approach to creating new generators compared to the standard library.

The package is designed for high-concurrency and high-performance environments with specific architectural decisions:

• No Source abstraction: In Go, the Source abstraction is considered a costly overhead that provides little value for most users.
• No top-level Seed(): To avoid the performance bottleneck of a global mutex-protected state, the package avoids a top-level Seed() function. Instead, it leverages goroutine-local state to ensure scalability as parallelism increases.
• Use of sfc64: The package uses sfc64 because it is fast, has withstood extensive testing without known flaws, and provides strong guarantees regarding period length and seed distance.

The pgregory.net/rand package is considered stable. It guarantees:

• API Stability: The public interface is stable.
• Deterministic Generation: Deterministic pseudo-random generation produces identical results across 32-bit and 64-bit architectures, and across both little-endian and big-endian systems.

Any changes to these deterministic results will only occur during a major version bump.

The package achieves high performance and quality by utilizing four core primitives:

1. Raw 64-bit generation: Uses sfc64 or goroutine-local runtime.fastrand64().
2. Floating-point generation: Implemented via floating-point multiplication.
3. Integer generation in range: Uses 32.64 or 64.128 fixed-point multiplication.

On most modern platforms, top-level functions use goroutine-local wyrand generators provided by the Go runtime to balance quality and concurrent execution speed.

To create a new random generator instance, use rand.New(). Unlike the standard library, which often requires manual seeding via rand.NewSource(time.Now().UnixNano()), pgregory.net/rand provides simplified initialization patterns:

• Use rand.New() for a default generator.
• Use rand.New(seed) (where seed is a uint64) to initialize with a specific seed.

// Default initialization
r := rand.New()

// Seeded initialization
r := rand.New(1)

Deciding which random number generator to use depends on your performance requirements:

• Use math/rand/v2 if you are not performing nanosecond-level performance profiling. It is a significant improvement over the original math/rand and is suitable for most general-purpose applications.
• Use pgregory.net/rand if you are counting nanoseconds and require maximum speed without compromising the quality of the random numbers.

The Rand type is a pseudo-random number generator based on the SFC64 algorithm. It is designed for high speed and high quality, making it faster and better than the standard math/rand package, but it is unsuitable for security-sensitive work (use crypto/rand instead).

Key Characteristics:

• State: Has 256 bits of state with an average period of ~2^255.
• Concurrency: Methods on a *Rand instance are not safe for concurrent use. If you need concurrent access, use the top-level package functions (like rand.Int()) which use goroutine-local sources.
• Determinism: Using New(seed...) or the Seed(uint64) method allows for reproducible sequences.

r := rand.New(42)
val := r.Uint64()

To generate a random number within a specific range, use the n suffix functions. These functions panic if the provided limit n is less than or equal to 0 (except for Uint32n and Uint64n which return 0 if n is 0).

• Intn(n int) int: Range [0, n).
• Int31n(n int32) int32: Range [0, n).
• Int63n(n int64) int64: Range [0, n).
• Uint32n(n uint32) uint32: Range [0, n). Returns 0 if n is 0.
• Uint64n(n uint64) uint64: Range [0, n). Returns 0 if n is 0.

// Returns a value in [0, 10)
val := rand.Intn(10)

// Returns a uint32 in [0, 100)
uval := rand.Uint32n(100)

The Read(p []byte) function generates len(p) pseudo-random bytes and writes them into the slice p. It always returns len(p) and a nil error.

bytes := make([]byte, 32)
n, err := rand.Read(bytes)
if err != nil {
    // handle error
}

Use New() to create a new pseudo-random number generator.

• Non-deterministic: If you call New() with no arguments, the generator is initialized to a non-deterministic state.
• Deterministic: If you provide a seed sequence (up to 3 uint64 values), the generator is initialized deterministically.

Warning: New will panic if the provided seed sequence length is greater than 3.

// Non-deterministic
r := rand.New()

// Deterministic with one seed
r := rand.New(12345)

// Deterministic with multiple seeds
r := rand.New(1, 2, 3)