json_out: make json_out_finished finish buffer.
[ccan] / 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