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

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