2 * The UCW Library -- Random numbers
4 * (c) 2020--2022 Pavel Charvat <pchar@ucw.cz>
6 * This software may be freely distributed and used according to the terms
7 * of the GNU Lesser General Public License.
13 #ifdef CONFIG_UCW_CLEAN_ABI
14 #define fastrand_new ucw_fastrand_new
15 #define fastrand_delete ucw_fastrand_delete
16 #define fastrand_set_seed ucw_fastrand_set_seed
17 #define fastrand_gen_seed_value ucw_fastrand_gen_seed_value
18 #define fastrand_gen_seed ucw_fastrand_gen_seed
19 #define fastrand_has_seed ucw_fastrand_has_seed
20 #define fastrand_reset ucw_fastrand_reset
21 #define fastrand_u32 ucw_fastrand_u32
22 #define fastrand_u64 ucw_fastrand_u64
23 #define fastrand_bits_u64 ucw_fastrand_bits_u64
24 #define fastrand_max ucw_fastrand_max
25 #define fastrand_max_u64 ucw_fastrand_max_u64
26 #define fastrand_mem ucw_fastrand_mem
27 #define fastrand_double ucw_fastrand_double
33 * Context structure for a fast pseudo-random generator.
34 * Useful for generating numbers in randomized algorithms, but not in critical things like cryptography.
35 * The library is generally thread-safe, but each context must be used by at most one thread at one time.
36 * Also be careful with fork() if you want to avoid the same numbers in subprocesses.
41 * Type for a seed value. Beware that some generators are only able to use the lowest 32 bits.
43 typedef u64 fastrand_seed_t;
46 * Allocate a new context. Should be paired with fastrand_delete().
47 * Don't forget to supply a seed before started to read randomness.
49 struct fastrand *fastrand_new(void);
50 void fastrand_delete(struct fastrand *c);
52 /** (Re)seed the context with given value. **/
53 void fastrand_set_seed(struct fastrand *c, fastrand_seed_t seed);
56 * Generate a seed for fastrand_set_seed().
58 * We currently mix these things (you can add more if needed):
60 * -- process id to deal with frequent fork() or startups
61 * -- counter to deal with multiple contexts, for example in threaded application
63 fastrand_seed_t fastrand_gen_seed_value(void);
65 /** (Re)seed the context with fastrand_gen_seed_value(). **/
66 fastrand_seed_t fastrand_gen_seed(struct fastrand *c);
68 /** Is the context seeded? **/
69 bool fastrand_has_seed(struct fastrand *c);
71 /** Reset the context to its initial state. Useful after a fork() to assert forgotten reseed. **/
72 void fastrand_reset(struct fastrand *c);
74 /** Uniformly generate 32 random bits. **/
75 u32 fastrand_u32(struct fastrand *c);
77 /** Uniformly generate 64 random bits. **/
78 u64 fastrand_u64(struct fastrand *c);
80 /** Uniformly generate [0, 64] random bits. **/
81 u64 fastrand_bits_u64(struct fastrand *c, uint bits);
83 /** Uniformly generate [0, 8*sizeof(uint)] random bits. **/
84 static inline uint fastrand_bits(struct fastrand *c, uint bits)
86 return fastrand_bits_u64(c, bits);
89 /** Uniformly generate a random number from range [0, bound-1], where @bound is [1, UINT_MAX]. **/
90 uint fastrand_max(struct fastrand *c, uint bound);
92 /** Uniformly generate a random number from range [0, bound-1], where @bound is [1, UINT64_MAX]. **/
93 u64 fastrand_max_u64(struct fastrand *c, u64 bound);
95 /** Generate @size random bytes. **/
96 void fastrand_mem(struct fastrand *c, void *ptr, size_t size);
98 /** Uniformly generate a random number from range [0.0, 1.0) + possible inaccuracies from basic floating point operations. **/
99 double fastrand_double(struct fastrand *c);