{-# OPTIONS_HADDOCK prune #-}
{-# LANGUAGE BangPatterns #-}

-- |
-- Module: Crypto.PRNG
-- Copyright: (c) 2026 Jared Tobin
-- License: MIT
-- Maintainer: Jared Tobin <jared@ppad.tech>
--
-- A fast, non-cryptographic pseudorandom number generator:
-- [xoshiro256++](https://prng.di.unimi.it/), by David Blackman and
-- Sebastiano Vigna.
--
-- The generator is mutable, living in any 'PrimMonad' (e.g. 'IO' or
-- 'ST s'), and is not thread-safe. Use one generator per thread,
-- deriving non-overlapping streams via 'copy' and 'jump' or
-- 'long_jump'.
--
-- Its output is predictable from a small sample; use "Crypto.CSPRNG"
-- for anything that must be unpredictable. "Crypto.PRNG.Pure" offers
-- the same generator, with the same output, as an immutable value.

module Crypto.PRNG (
    -- * Generator
    Gen
  , new
  , new_system
  , from_state

    -- * Output
  , word64
  , word64_range
  , int_range
  , double

    -- * Streams
  , copy
  , jump
  , long_jump
  ) where

import Control.Monad.Primitive (PrimMonad, PrimState)
import Control.Monad.ST (ST)
import qualified Crypto.Range as Range
import Crypto.Xoshiro (S(..))
import qualified Crypto.Xoshiro as X
import Data.Bits ((.>>.))
import qualified Data.Primitive.PrimArray as PA
import Data.Word (Word64)
import GHC.Exts (RealWorld)

-- utils ----------------------------------------------------------------------

fi :: (Integral a, Num b) => a -> b
fi :: forall a b. (Integral a, Num b) => a -> b
fi = a -> b
forall a b. (Integral a, Num b) => a -> b
fromIntegral
{-# INLINE fi #-}

-- generator ------------------------------------------------------------------

-- | A xoshiro256++ generator.
newtype Gen s = Gen (PA.MutablePrimArray s Word64)

read_s :: PrimMonad m => Gen (PrimState m) -> m S
read_s :: forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m S
read_s (Gen MutablePrimArray (PrimState m) Word64
g) = do
  !s0 <- MutablePrimArray (PrimState m) Word64 -> Int -> m Word64
forall a (m :: * -> *).
(Prim a, PrimMonad m) =>
MutablePrimArray (PrimState m) a -> Int -> m a
PA.readPrimArray MutablePrimArray (PrimState m) Word64
g Int
0
  !s1 <- PA.readPrimArray g 1
  !s2 <- PA.readPrimArray g 2
  !s3 <- PA.readPrimArray g 3
  pure $! S s0 s1 s2 s3
{-# INLINE read_s #-}

write_s :: PrimMonad m => Gen (PrimState m) -> S -> m ()
write_s :: forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> S -> m ()
write_s (Gen MutablePrimArray (PrimState m) Word64
g) (S Word64
s0 Word64
s1 Word64
s2 Word64
s3) = do
  MutablePrimArray (PrimState m) Word64 -> Int -> Word64 -> m ()
forall a (m :: * -> *).
(Prim a, PrimMonad m) =>
MutablePrimArray (PrimState m) a -> Int -> a -> m ()
PA.writePrimArray MutablePrimArray (PrimState m) Word64
g Int
0 Word64
s0
  MutablePrimArray (PrimState m) Word64 -> Int -> Word64 -> m ()
forall a (m :: * -> *).
(Prim a, PrimMonad m) =>
MutablePrimArray (PrimState m) a -> Int -> a -> m ()
PA.writePrimArray MutablePrimArray (PrimState m) Word64
g Int
1 Word64
s1
  MutablePrimArray (PrimState m) Word64 -> Int -> Word64 -> m ()
forall a (m :: * -> *).
(Prim a, PrimMonad m) =>
MutablePrimArray (PrimState m) a -> Int -> a -> m ()
PA.writePrimArray MutablePrimArray (PrimState m) Word64
g Int
2 Word64
s2
  MutablePrimArray (PrimState m) Word64 -> Int -> Word64 -> m ()
forall a (m :: * -> *).
(Prim a, PrimMonad m) =>
MutablePrimArray (PrimState m) a -> Int -> a -> m ()
PA.writePrimArray MutablePrimArray (PrimState m) Word64
g Int
3 Word64
s3
{-# INLINE write_s #-}

alloc :: PrimMonad m => S -> m (Gen (PrimState m))
alloc :: forall (m :: * -> *). PrimMonad m => S -> m (Gen (PrimState m))
alloc S
s = do
  g <- (MutablePrimArray (PrimState m) Word64 -> Gen (PrimState m))
-> m (MutablePrimArray (PrimState m) Word64)
-> m (Gen (PrimState m))
forall a b. (a -> b) -> m a -> m b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap MutablePrimArray (PrimState m) Word64 -> Gen (PrimState m)
forall s. MutablePrimArray s Word64 -> Gen s
Gen (Int -> m (MutablePrimArray (PrimState m) Word64)
forall (m :: * -> *) a.
(PrimMonad m, Prim a) =>
Int -> m (MutablePrimArray (PrimState m) a)
PA.newPrimArray Int
4)
  write_s g s
  pure g
{-# INLINE alloc #-}

-- | Create a generator from a 64-bit seed, expanded to the full
--   256-bit state via splitmix64, per the xoshiro authors'
--   recommendation.
--
--   >>> gen <- new 42
--   >>> word64 gen
--   15021278609987233951
new :: PrimMonad m => Word64 -> m (Gen (PrimState m))
new :: forall (m :: * -> *).
PrimMonad m =>
Word64 -> m (Gen (PrimState m))
new = S -> m (Gen (PrimState m))
forall (m :: * -> *). PrimMonad m => S -> m (Gen (PrimState m))
alloc (S -> m (Gen (PrimState m)))
-> (Word64 -> S) -> Word64 -> m (Gen (PrimState m))
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Word64 -> S
X.seed
{-# INLINABLE new #-}
{-# SPECIALIZE new :: Word64 -> IO (Gen RealWorld) #-}
{-# SPECIALIZE new :: Word64 -> ST s (Gen s) #-}

-- | Create a generator from the given 256-bit state, returning
--   'Nothing' if it is all zero.
--
--   >>> Just gen <- from_state 1 2 3 4
--   >>> word64 gen
--   41943041
from_state
  :: PrimMonad m
  => Word64
  -> Word64
  -> Word64
  -> Word64
  -> m (Maybe (Gen (PrimState m)))
from_state :: forall (m :: * -> *).
PrimMonad m =>
Word64
-> Word64 -> Word64 -> Word64 -> m (Maybe (Gen (PrimState m)))
from_state Word64
s0 Word64
s1 Word64
s2 Word64
s3 = (S -> m (Gen (PrimState m)))
-> Maybe S -> m (Maybe (Gen (PrimState m)))
forall (t :: * -> *) (f :: * -> *) a b.
(Traversable t, Applicative f) =>
(a -> f b) -> t a -> f (t b)
forall (f :: * -> *) a b.
Applicative f =>
(a -> f b) -> Maybe a -> f (Maybe b)
traverse S -> m (Gen (PrimState m))
forall (m :: * -> *). PrimMonad m => S -> m (Gen (PrimState m))
alloc (Word64 -> Word64 -> Word64 -> Word64 -> Maybe S
X.from_words Word64
s0 Word64
s1 Word64
s2 Word64
s3)
{-# INLINABLE from_state #-}

-- | Create a generator with a 256-bit state drawn from the operating
--   system's entropy source, returning 'Nothing' if that fails.
--
--   >>> Just gen <- new_system
new_system :: IO (Maybe (Gen RealWorld))
new_system :: IO (Maybe (Gen RealWorld))
new_system = IO (Maybe S)
X.system IO (Maybe S)
-> (Maybe S -> IO (Maybe (Gen RealWorld)))
-> IO (Maybe (Gen RealWorld))
forall a b. IO a -> (a -> IO b) -> IO b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= (S -> IO (Gen RealWorld)) -> Maybe S -> IO (Maybe (Gen RealWorld))
forall (t :: * -> *) (f :: * -> *) a b.
(Traversable t, Applicative f) =>
(a -> f b) -> t a -> f (t b)
forall (f :: * -> *) a b.
Applicative f =>
(a -> f b) -> Maybe a -> f (Maybe b)
traverse S -> IO (Gen RealWorld)
S -> IO (Gen (PrimState IO))
forall (m :: * -> *). PrimMonad m => S -> m (Gen (PrimState m))
alloc

-- output ---------------------------------------------------------------------

-- | Generate a uniformly-distributed 'Word64'.
--
--   >>> Just gen <- from_state 1 2 3 4
--   >>> word64 gen
--   41943041
--   >>> word64 gen
--   58720359
word64 :: PrimMonad m => Gen (PrimState m) -> m Word64
word64 :: forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m Word64
word64 Gen (PrimState m)
gen = do
  !s <- Gen (PrimState m) -> m S
forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m S
read_s Gen (PrimState m)
gen
  write_s gen (X.next s)
  pure $! X.output s
{-# INLINE word64 #-}

-- | Generate a uniformly-distributed 'Word64' in the given inclusive
--   range, whose bounds may be given in either order.
--
--   The result is unbiased; see 'int_range'.
--
--   >>> gen <- new 42
--   >>> word64_range 1 6 gen
--   5
word64_range
  :: PrimMonad m => Word64 -> Word64 -> Gen (PrimState m) -> m Word64
word64_range :: forall (m :: * -> *).
PrimMonad m =>
Word64 -> Word64 -> Gen (PrimState m) -> m Word64
word64_range Word64
a Word64
b Gen (PrimState m)
gen = do
  let !lo :: Word64
lo = Word64 -> Word64 -> Word64
forall a. Ord a => a -> a -> a
min Word64
a Word64
b
      !hi :: Word64
hi = Word64 -> Word64 -> Word64
forall a. Ord a => a -> a -> a
max Word64
a Word64
b
  !r <- m Word64 -> Word64 -> m Word64
forall (m :: * -> *). Monad m => m Word64 -> Word64 -> m Word64
Range.upto (Gen (PrimState m) -> m Word64
forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m Word64
word64 Gen (PrimState m)
gen) (Word64
hi Word64 -> Word64 -> Word64
forall a. Num a => a -> a -> a
- Word64
lo)
  pure $! lo + r
{-# INLINE word64_range #-}

-- | Generate a uniformly-distributed 'Int' in the given inclusive
--   range, whose bounds may be given in either order.
--
--   The result is unbiased, via Lemire's method: an occasional draw is
--   rejected and replaced, so the number of words consumed varies.
--
--   >>> gen <- new 42
--   >>> int_range (-10) 10 gen
--   7
int_range :: PrimMonad m => Int -> Int -> Gen (PrimState m) -> m Int
int_range :: forall (m :: * -> *).
PrimMonad m =>
Int -> Int -> Gen (PrimState m) -> m Int
int_range Int
a Int
b Gen (PrimState m)
gen = do
  let !lo :: Int
lo = Int -> Int -> Int
forall a. Ord a => a -> a -> a
min Int
a Int
b
      !hi :: Int
hi = Int -> Int -> Int
forall a. Ord a => a -> a -> a
max Int
a Int
b
  !r <- m Word64 -> Word64 -> m Word64
forall (m :: * -> *). Monad m => m Word64 -> Word64 -> m Word64
Range.upto (Gen (PrimState m) -> m Word64
forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m Word64
word64 Gen (PrimState m)
gen) (Int -> Word64
forall a b. (Integral a, Num b) => a -> b
fi Int
hi Word64 -> Word64 -> Word64
forall a. Num a => a -> a -> a
- Int -> Word64
forall a b. (Integral a, Num b) => a -> b
fi Int
lo)
  pure $! lo + fi r
{-# INLINE int_range #-}

-- | Generate a uniformly-distributed 'Double' in [0, 1), from the
--   upper 53 bits of a 'Word64'.
--
--   >>> Just gen <- from_state 1 2 3 4
--   >>> double gen
--   2.2737367544323206e-12
double :: PrimMonad m => Gen (PrimState m) -> m Double
double :: forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m Double
double Gen (PrimState m)
gen = do
  !w <- Gen (PrimState m) -> m Word64
forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m Word64
word64 Gen (PrimState m)
gen
  -- 2 ^ -53
  pure $! fi (w .>>. 11) * 1.1102230246251565e-16
{-# INLINE double #-}

-- streams --------------------------------------------------------------------

-- | Copy a generator. The copy produces the same output as the
--   original, independently of it.
--
--   >>> gen <- new 42
--   >>> cop <- copy gen
--   >>> (==) <$> word64 gen <*> word64 cop
--   True
copy :: PrimMonad m => Gen (PrimState m) -> m (Gen (PrimState m))
copy :: forall (m :: * -> *).
PrimMonad m =>
Gen (PrimState m) -> m (Gen (PrimState m))
copy Gen (PrimState m)
gen = Gen (PrimState m) -> m S
forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m S
read_s Gen (PrimState m)
gen m S -> (S -> m (Gen (PrimState m))) -> m (Gen (PrimState m))
forall a b. m a -> (a -> m b) -> m b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= S -> m (Gen (PrimState m))
forall (m :: * -> *). PrimMonad m => S -> m (Gen (PrimState m))
alloc
{-# INLINE copy #-}

-- | Advance a generator by 2 ^ 128 outputs.
--
--   Copying and then jumping repeatedly yields up to 2 ^ 128
--   non-overlapping streams of 2 ^ 128 outputs each, e.g. one per
--   thread.
--
--   >>> gen <- new 42
--   >>> one <- copy gen
--   >>> jump gen
--   >>> two <- copy gen
--   >>> jump gen
jump :: PrimMonad m => Gen (PrimState m) -> m ()
jump :: forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m ()
jump Gen (PrimState m)
gen = do
  !s <- Gen (PrimState m) -> m S
forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m S
read_s Gen (PrimState m)
gen
  write_s gen (X.jump s)
{-# INLINABLE jump #-}

-- | Advance a generator by 2 ^ 192 outputs.
--
--   Copying and long-jumping repeatedly yields up to 2 ^ 64 starting
--   points, from each of which 'jump' yields 2 ^ 64 non-overlapping
--   streams.
--
--   >>> gen <- new 42
--   >>> long_jump gen
long_jump :: PrimMonad m => Gen (PrimState m) -> m ()
long_jump :: forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m ()
long_jump Gen (PrimState m)
gen = do
  !s <- Gen (PrimState m) -> m S
forall (m :: * -> *). PrimMonad m => Gen (PrimState m) -> m S
read_s Gen (PrimState m)
gen
  write_s gen (X.long_jump s)
{-# INLINABLE long_jump #-}