randish

README

Randish

Randish is a Go package that provides pseudo-random number generators which are unique and thread-safe.

Do not use this for cryptography! If you need a package for that purpose, please use the crypto/rand package instead.

Features

• Rand(): Generates a new pseudo-random number generator that is initialized with a unique seed value.
• RandS(): Singleton and thread-safe variant of the Rand() function. Returns a globally unique instance of a pseudo-random number generator.
• RandSA(): Initializes an array of pseudo-random number generators and returns one from the array using pseudo-random selection.
• Seed(): Function that generates a seed for pseudo-random number generation using various system and context-specific elements.

Getting Started

Prerequisites

• Go 1.7 or later

Installation

1. Download randish using the go get command:

   go get github.com/TechMDW/randish
   

2. Import randish in your code:

   import "github.com/TechMDW/randish"
   

3. Use the functions as needed.

Usage

Here is an example of how to use randish in your Go code:

package main

import (
    "github.com/TechMDW/randish"
)

func main() {
    // Generate a new random number generator
    //
    // Returns the *rand.Rand from "math/rand" package
    r := randish.Rand()

    // Generate a random number
    num := r.Int()

    println(num)
}

TODO

• Write README
• Version control

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

Maintained by @TechMDW - contact@techmdw.com - Feel free to contact us if you have any questions.

Documentation

Index

• func Rand() *rand.Rand
• func RandS() *rand.Rand
• func RandSA() *rand.Rand
• func RandTest() (randish *rand.Rand, seed int64)
• func Seed() int64

Functions

func Rand

func Rand() *rand.Rand

Rand returns a new pseudo-random number generator, *rand.Rand, which is initialized with a unique seed value obtained from the Seed function. The Seed function uses a mix of various system and context-specific elements to generate a unique seed value. This guarantees that the sequence of pseudo-random numbers generated by the returned *rand.Rand object is distinct.

func RandS

func RandS() *rand.Rand

RandS is a singleton and thread-safe variant of the Rand function. It returns a globally unique instance of a *rand.Rand, a pseudo-random number generator. This generator is initialized with a unique seed value obtained from the Seed function, which utilizes various system and context-specific elements. The singleton nature of this function ensures that the same *rand.Rand instance is returned across multiple calls, across all threads. The thread-safety guarantees that the singleton instance is correctly initialized even in a multi-threaded context.

func RandSA

func RandSA() *rand.Rand

RandSA initializes an array of *rand.Rand instances, if not already done, and returns a *rand.Rand chosen from the array using pseudo-random selection.

func RandTest

func RandTest() (randish *rand.Rand, seed int64)

Don't use this function directly. Use Rand or RandS instead.

func Seed

func Seed() int64

Seed is a function that generates a seed for pseudo-random number generation. It uses various unique and variable elements from the system as a basis for the seed, which is then used to generate unique random numbers across multiple calls.

The seed is initially set to the current Unix timestamp in nanoseconds. A new random source is then created based on this timestamp, which is used for further calculations.

The function gathers system-specific data, including the current hostname, process ID, user ID, group ID, working directory, and the number of logical CPUs on the system.

It also gathers some context-specific data by calling the runtime.Caller function. This returns information about the function that is invoking Seed, including its file name, line number, and a counter that represents the current instruction address.

The function then reads a random number from the crypto/rand package to further enhance the randomness of the seed.

After that, the function iterates through each environment variable, converting each one to an integer hash. The generated hash is used in a random mathematical operation (addition, subtraction, or multiplication) to modify the seed value.

Each piece of system-specific and context-specific data, as well as the randomly generated number from crypto/rand, is also used in the same way, to further modify the seed value.

The resulting seed is a complex, unique value that can be used to seed a pseudo-random number generator (such as the one in the math/rand package) to ensure that the generated sequence of numbers is as random and unique as possible across different contexts and systems.