git.ozlabs.org Git - ccan/blob - ccan/isaac/isaac.h

   1 /* CC0 (Public domain) - see LICENSE file for details */
   2 #if !defined(_isaac_H)
   3 # define _isaac_H (1)
   4 # include <stdint.h>
   5
   6
   7
   8 typedef struct isaac_ctx isaac_ctx;
   9
  10
  11
  12 /*This value may be lowered to reduce memory usage on embedded platforms, at
  13    the cost of reducing security and increasing bias.
  14   Quoting Bob Jenkins: "The current best guess is that bias is detectable after
  15    2**37 values for [ISAAC_SZ_LOG]=3, 2**45 for 4, 2**53 for 5, 2**61 for 6,
  16    2**69 for 7, and 2**77 values for [ISAAC_SZ_LOG]=8."*/
  17 #define ISAAC_SZ_LOG      (8)
  18 #define ISAAC_SZ          (1<<ISAAC_SZ_LOG)
  19 #define ISAAC_SEED_SZ_MAX (ISAAC_SZ<<2)
  20
  21
  22
  23 /*ISAAC is the most advanced of a series of pseudo-random number generators
  24    designed by Robert J. Jenkins Jr. in 1996.
  25   http://www.burtleburtle.net/bob/rand/isaac.html
  26   To quote:
  27     No efficient method is known for deducing their internal states.
  28     ISAAC requires an amortized 18.75 instructions to produce a 32-bit value.
  29     There are no cycles in ISAAC shorter than 2**40 values.
  30     The expected cycle length is 2**8295 values.*/
  31 struct isaac_ctx{
  32   unsigned n;
  33   uint32_t r[ISAAC_SZ];
  34   uint32_t m[ISAAC_SZ];
  35   uint32_t a;
  36   uint32_t b;
  37   uint32_t c;
  38 };
  39
  40
  41 /**
  42  * isaac_init - Initialize an instance of the ISAAC random number generator.
  43  * @_ctx:   The instance to initialize.
  44  * @_seed:  The specified seed bytes.
  45  *          This may be NULL if _nseed is less than or equal to zero.
  46  * @_nseed: The number of bytes to use for the seed.
  47  *          If this is greater than ISAAC_SEED_SZ_MAX, the extra bytes are
  48  *           ignored.
  49  */
  50 void isaac_init(isaac_ctx *_ctx,const unsigned char *_seed,int _nseed);
  51
  52 /**
  53  * isaac_reseed - Mix a new batch of entropy into the current state.
  54  * To reset ISAAC to a known state, call isaac_init() again instead.
  55  * @_ctx:   The instance to reseed.
  56  * @_seed:  The specified seed bytes.
  57  *          This may be NULL if _nseed is zero.
  58  * @_nseed: The number of bytes to use for the seed.
  59  *          If this is greater than ISAAC_SEED_SZ_MAX, the extra bytes are
  60  *           ignored.
  61  */
  62 void isaac_reseed(isaac_ctx *_ctx,const unsigned char *_seed,int _nseed);
  63 /**
  64  * isaac_next_uint32 - Return the next random 32-bit value.
  65  * @_ctx: The ISAAC instance to generate the value with.
  66  */
  67 uint32_t isaac_next_uint32(isaac_ctx *_ctx);
  68 /**
  69  * isaac_next_uint - Uniform random integer less than the given value.
  70  * @_ctx: The ISAAC instance to generate the value with.
  71  * @_n:   The upper bound on the range of numbers returned (not inclusive).
  72  *        This must be greater than zero and less than 2**32.
  73  *        To return integers in the full range 0...2**32-1, use
  74  *         isaac_next_uint32() instead.
  75  * Return: An integer uniformly distributed between 0 and _n-1 (inclusive).
  76  */
  77 uint32_t isaac_next_uint(isaac_ctx *_ctx,uint32_t _n);
  78 /**
  79  * isaac_next_float - Uniform random float in the range [0,1).
  80  * @_ctx: The ISAAC instance to generate the value with.
  81  * Returns a high-quality float uniformly distributed between 0 (inclusive)
  82  *  and 1 (exclusive).
  83  * All of the float's mantissa bits are random, e.g., the least significant bit
  84  *  may still be non-zero even if the value is less than 0.5, and any
  85  *  representable float in the range [0,1) has a chance to be returned, though
  86  *  values very close to zero become increasingly unlikely.
  87  * To generate cheaper float values that do not have these properties, use
  88  *   ldexpf((float)isaac_next_uint32(_ctx),-32);
  89  */
  90 float isaac_next_float(isaac_ctx *_ctx);
  91 /**
  92  * isaac_next_signed_float - Uniform random float in the range (-1,1).
  93  * @_ctx: The ISAAC instance to generate the value with.
  94  * Returns a high-quality float uniformly distributed between -1 and 1
  95  *  (exclusive).
  96  * All of the float's mantissa bits are random, e.g., the least significant bit
  97  *  may still be non-zero even if the magnitude is less than 0.5, and any
  98  *  representable float in the range (-1,1) has a chance to be returned, though
  99  *  values very close to zero become increasingly unlikely.
 100  * To generate cheaper float values that do not have these properties, use
 101  *   ldexpf((float)isaac_next_uint32(_ctx),-31)-1;
 102  *  though this returns values in the range [-1,1).
 103  */
 104 float isaac_next_signed_float(isaac_ctx *_ctx);
 105 /**
 106  * isaac_next_double - Uniform random double in the range [0,1).
 107  * @_ctx: The ISAAC instance to generate the value with.
 108  * Returns a high-quality double uniformly distributed between 0 (inclusive)
 109  *  and 1 (exclusive).
 110  * All of the double's mantissa bits are random, e.g., the least significant
 111  *  bit may still be non-zero even if the value is less than 0.5, and any
 112  *  representable double in the range [0,1) has a chance to be returned, though
 113  *  values very close to zero become increasingly unlikely.
 114  * To generate cheaper double values that do not have these properties, use
 115  *   ldexp((double)isaac_next_uint32(_ctx),-32);
 116  */
 117 double isaac_next_double(isaac_ctx *_ctx);
 118 /**
 119  * isaac_next_signed_double - Uniform random double in the range (-1,1).
 120  * @_ctx: The ISAAC instance to generate the value with.
 121  * Returns a high-quality double uniformly distributed between -1 and 1
 122  *  (exclusive).
 123  * All of the double's mantissa bits are random, e.g., the least significant
 124  *  bit may still be non-zero even if the value is less than 0.5, and any
 125  *  representable double in the range (-1,1) has a chance to be returned,
 126  *  though values very close to zero become increasingly unlikely.
 127  * To generate cheaper double values that do not have these properties, use
 128  *   ldexp((double)isaac_next_uint32(_ctx),-31)-1;
 129  *  though this returns values in the range [-1,1).
 130  */
 131 double isaac_next_signed_double(isaac_ctx *_ctx);
 132
 133 #endif