FastRng.ThreadSafe 1.0.4

FastRng.Generator

An ultra-fast, thread-safe cascade random number generator (RNG) optimized for .NET 10.

This generator features a multi-layered, structural state permutation engine based on isolated RC4-style layers. It operates on a continuous 1.5KB flat block of memory perfectly aligned to sit inside the processor's L1 Data Cache. By completely omitting bounds-checking using Unsafe memory mapping and avoiding cross-layer state leakage, it preserves flawless 1-to-1 array permutations indefinitely.

Mathematical Foundations

1. Permutation Stability and State Space

The internal state of the generator consists of 6 isolated layers ($M_0, M_1, \dots, M_5$), where each layer is an array containing a strict permutation of the byte space $\mathbb{Z}_{256} = {0, 1, \dots, 255}$.

Because the algorithm relies strictly on transpositions (swaps) inside individual boundaries: $$\forall m \in, \quad \sum_{k=0}^{255} M_m[k] = 32640$$

No values are cloned, and no values are deleted. The card deck is always pristine. The theoretical total state space (period bounds) of the system is defined by the permutations of all layers and index offsets: $$\Omega = (256!)^6 \times 256^2 \approx 10^{3044}$$ This makes structural cycle repetition mathematically impossible over any practical software lifecycle.

2. Cascading Diffusion and Chaotic Trajectory

The generator utilizes a forward feedback mechanism where the byte value extracted from layer $n$ acts as an immediate pointer index for layer $n+1$. The recursion depth $L$ is a dynamic variable determined on-the-fly by the state entropy: $$L = (V_0 \pmod 4) + 3 \quad \implies \quad L \in [3, 6]$$

The transitional stepping rules for each layer $m$ satisfy: $$j_m = (j_{m-1} + M_m[i_m]) \pmod{256}$$ $$\text{Swap}(M_m[i_m], M_m[j_m])$$ $$\text{Output } V_m = M_m[(M_m[i_m] + M_m[j_m]) \pmod{256}]$$

By passing $V_m$ straight to the next layer as the pointer index ($i_{m+1} = V_m$), the algorithm creates an algorithmic Avalanche Effect. A single bit flipped at layer 0 yields completely uncorrelated trajectories across the deep matrix blocks.

3. Statistical Validation

Chi-Squared ($\chi^2$) Uniformity Analysis

The uniform probability distribution over long-range execution paths is verified using Pearson's $\chi^2$ Goodness-of-Fit test over a grid of $65,536$ coordinate pairs: $$\chi^2 = \sum_{r=0}^{255} \sum_{c=0}^{255} \frac{(A_{r,c} - E)^2}{E}$$ Where $A_{r,c}$ is the actual count of the sequential transition $r \to c$, and $E$ is the expected mathematical uniform mean ($\approx 152.58$ over 10,000,000 samples).

The generator consistently yields $\chi^2 \in [64000, 67000]$ for $65,535$ degrees of freedom at a $99%$ confidence interval, perfectly matching the natural randomness curves of physical matter.

Gaussian Curve Behavior (Pairwise Cluster Bounds)

Under a high-volume sample load, the cell counts naturally obey the Central Limit Theorem. The variation around the expected mean behaves as a classic Gaussian bell curve with a standard deviation of: $$\sigma = \sqrt{E} = \sqrt{152.58} \approx 12.35$$

The absolute cluster ceiling for natural random path clustering hits a predictable limit of $+4.5\sigma \approx 208$ transitions per cell. This structure preserves organic randomness properties, completely passing heavy spatial tests.

Features

• 🏎️ Cache-Localized Latency: State tracking operations remain inside a fast 1.5KB block.
• 🧵 Lock-Free Concurrency: Leverages [ThreadStatic] boundaries for zero-lock threading safety.
• 🛡️ Zero Allocation Overhead: Native support for stackalloc and Span<byte> buffers.
• 🧩 Ecosystem Compliance: Inherits directly from System.Random for generic polymorphism.

Installation

NuGet\Install-Package FastRng.Generator

Quick Start

using FastRng.ThreadSafe;

// Access the lock-free, thread-isolated instance
var rng = ThreadSafeCascadeGenerator.Instance;

// Generate a high-speed single byte (0 - 255)
byte discreteByte = rng.NextByte();

// Native support for standard ranges and floats
int diceRoll = rng.Next(1, 7);
double weight = rng.NextDouble();

// Fast buffering without triggering the Garbage Collector (GC)
Span<byte> buffer = stackalloc byte;
rng.NextBytes(buffer);