libghc-tf-random-doc 0.5-7build2 / usr / share / doc / libghc-tf-random-doc / html / tf-random.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | High-quality splittable pseudorandom number generator
--   
--   This package contains an implementation of a high-quality splittable
--   pseudorandom number generator. The generator is based on a
--   cryptographic hash function built on top of the ThreeFish block
--   cipher. See the paper <i>Splittable Pseudorandom Number Generators
--   Using Cryptographic Hashing</i> by Claessen, Palka for details and the
--   rationale of the design.
--   
--   The package provides the following:
--   
--   <ul>
--   <li>A splittable PRNG that implements the standard
--   <a>System.Random.RandomGen</a> class.</li>
--   <li>The generator also implements an alternative version of the
--   <a>System.Random.TF.Gen.RandomGen</a> class (exported from
--   <a>System.Random.TF.Gen</a>), which requires the generator to return
--   pseudorandom integers from the full 32-bit range, and contains an
--   n-way split function.</li>
--   <li>An alternative version of the <tt>Random</tt> class is provided,
--   which is linked to the new <tt>RandomGen</tt> class, together with
--   <tt>Random</tt> instances for some integral types.</li>
--   <li>Two functions for initialising the generator with a
--   non-deterministic seed: one using the system time, and one using the
--   <tt>/dev/urandom</tt> UNIX special file.</li>
--   </ul>
--   
--   The package uses an adapted version of the reference C implementation
--   of ThreeFish from the reference package of the Skein hash function
--   (<a>https://www.schneier.com/skein.html</a>), originally written by
--   Doug Whiting.
--   
--   Please note that even though the generator provides very high-quality
--   pseudorandom numbers, it has not been designed with cryptographic
--   applications in mind.
@package tf-random
@version 0.5


-- | This module provides the <a>TFGen</a> generator and the alternative
--   <a>RandomGen</a> class. <a>TFGen</a> also implements the standard
--   <a>RandomGen</a> class.
module System.Random.TF.Gen

-- | The generator type
data TFGen

-- | Alternative <a>RandomGen</a> class with a modified <a>next</a>
--   operation, and added <a>splitn</a> and <a>level</a> operations.
--   
--   Using the generator requires that no more than one operation is called
--   on the same generator state, as the implementation does not guarantee
--   pseudorandomness otherwise. As an exception, calling <a>splitn</a>
--   many times on the same generator state is allowed as long as the
--   'bits' argument is the same for all the calls.
class RandomGen g

-- | <a>next</a> returns a <a>Word32</a> that appears to have been chosen
--   uniformly at random, and a new generator state.
next :: RandomGen g => g -> (Word32, g)

-- | <a>split</a> returns two derived generator states that appear to be
--   independent pseudorandom number generators.
split :: RandomGen g => g -> (g, g)

-- | <a>splitn</a> is the n-way split operation used to create many derived
--   generator states in one go. Application of <a>splitn</a> to two first
--   arguments should be shared between different applications of the index
--   argument to avoid unnecessary repeated computations.
--   
--   The following code creates ten 'independent' generator states. Number
--   '4' comes from the fact that at least four bits are needed to encode
--   ten different indices.
--   
--   <pre>
--   f :: RandomGen g =&gt; g -&gt; [g]
--   f r = map (splitn r 4) [0..9]
--   </pre>
splitn :: RandomGen g => g -> Int -> Word32 -> g

-- | <a>level</a> is a 'hint' operation that may cause an iteration of work
--   of the generator be performed prematurely in order to prevent the
--   subsequent operations from being expensive. It is meant to be called
--   before a <a>splitn</a> operation, which is expected to be evaluated a
--   very large number indices. Calling <a>level</a> in such case might
--   decrease the total amount of work performed.
level :: RandomGen g => g -> g

-- | Create a generator from a random seed.
seedTFGen :: (Word64, Word64, Word64, Word64) -> TFGen
instance GHC.Read.Read System.Random.TF.Gen.TFGenR
instance GHC.Show.Show System.Random.TF.Gen.TFGenR
instance GHC.Show.Show System.Random.TF.Gen.Hex
instance GHC.Read.Read System.Random.TF.Gen.Hex
instance GHC.Show.Show System.Random.TF.Gen.TFGen
instance GHC.Read.Read System.Random.TF.Gen.TFGen
instance System.Random.RandomGen System.Random.TF.Gen.TFGen
instance System.Random.TF.Gen.RandomGen System.Random.TF.Gen.TFGen

module System.Random.TF.Init

-- | Derive a new generator instance from the global RNG using split. This
--   is the default way of obtaining a new RNG instance. Initial generator
--   is seeded using <a>mkSeedUnix</a> on UNIX, and <a>mkSeedTime</a>
--   otherwise. This should be eventually replaced with proper seeding.
newTFGen :: IO TFGen

-- | Quick and dirty way of creating a deterministically seeded generator.
mkTFGen :: Int -> TFGen

-- | Use system time create the random seed. This method of seeding may not
--   be relible.
mkSeedTime :: IO (Word64, Word64, Word64, Word64)

-- | Use the UNIX special file <tt>/dev/urandom</tt> to create the seed.
--   Inspired by <tt>random-mwc</tt>.
mkSeedUnix :: IO (Word64, Word64, Word64, Word64)

-- | Create a seed and used it to seed an instance of TFGen. Uses
--   <a>mkSeedUnix</a> on UNIX, and <a>mkSeedTime</a> otherwise.
initTFGen :: IO TFGen


-- | This module defines alternative <a>Random</a> instances for common
--   integral types, which make use of the <a>RandomGen</a> class from
--   <a>System.Random.TF.Gen</a>.
module System.Random.TF.Instances
class Random a where randomRs ival g = myUnfoldr (randomR ival) g randoms g = myUnfoldr random g
randomR :: (Random a, RandomGen g) => (a, a) -> g -> (a, g)
random :: (Random a, RandomGen g) => g -> (a, g)
randomRs :: (Random a, RandomGen g) => (a, a) -> g -> [a]
randoms :: (Random a, RandomGen g) => g -> [a]
randomEnum :: (Enum a, RandomGen g) => (a, a) -> g -> (a, g)
instance System.Random.TF.Instances.Random GHC.Types.Int
instance System.Random.TF.Instances.Random GHC.Types.Char
instance System.Random.TF.Instances.Random GHC.Types.Bool
instance System.Random.TF.Instances.Random GHC.Integer.Type.Integer
instance System.Random.TF.Instances.Random GHC.Word.Word32
instance System.Random.TF.Instances.Random GHC.Word.Word64
instance System.Random.TF.Instances.Random GHC.Int.Int32
instance System.Random.TF.Instances.Random GHC.Int.Int64
instance System.Random.TF.Instances.Random GHC.Word.Word8
instance System.Random.TF.Instances.Random GHC.Int.Int8
instance System.Random.TF.Instances.Random GHC.Word.Word16
instance System.Random.TF.Instances.Random GHC.Int.Int16


-- | This module exports <a>System.Random.TF.Gen</a> and
--   <a>System.Random.TF.Init</a> modules without exporting the alternative
--   <a>RandomGen</a> class from <a>System.Random.TF.Gen</a>. To use this
--   class and the <a>Random</a> instances written for it, please import
--   <a>System.Random.TF.Gen</a> and <a>System.Random.TF.Instances</a>
--   directly.
module System.Random.TF