ucw/random.h

   1 /*
   2  *      The UCW Library -- Random numbers
   3  *
   4  *      (c) 2020--2022 Pavel Charvat <pchar@ucw.cz>
   5  *
   6  *      This software may be freely distributed and used according to the terms
   7  *      of the GNU Lesser General Public License.
   8  */
   9
  10 #ifndef _UCW_RANDOM_H
  11 #define _UCW_RANDOM_H
  12
  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
  28 #endif
  29
  30 /* random-fast.c */
  31
  32 /**
  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.
  37  **/
  38 struct fastrand;
  39
  40 /**
  41  * Type for a seed value. Beware that some generators are only able to use the lowest 32 bits.
  42  **/
  43 typedef u64 fastrand_seed_t;
  44
  45 /**
  46  * Allocate a new context. Should be paired with fastrand_delete().
  47  * Don't forget to supply a seed before started to read randomness.
  48  **/
  49 struct fastrand *fastrand_new(void);
  50 void fastrand_delete(struct fastrand *c);
  51
  52 /** (Re)seed the context with given value. **/
  53 void fastrand_set_seed(struct fastrand *c, fastrand_seed_t seed);
  54
  55 /**
  56  * Generate a seed for fastrand_set_seed().
  57  *
  58  * We currently mix these things (you can add more if needed):
  59  * -- current time
  60  * -- process id to deal with frequent fork() or startups
  61  * -- counter to deal with multiple contexts, for example in threaded application
  62  **/
  63 fastrand_seed_t fastrand_gen_seed_value(void);
  64
  65 /** (Re)seed the context with fastrand_gen_seed_value(). **/
  66 fastrand_seed_t fastrand_gen_seed(struct fastrand *c);
  67
  68 /** Is the context seeded? **/
  69 bool fastrand_has_seed(struct fastrand *c);
  70
  71 /** Reset the context to its initial state. Useful after a fork() to assert forgotten reseed. **/
  72 void fastrand_reset(struct fastrand *c);
  73
  74 /** Uniformly generate 32 random bits. **/
  75 u32 fastrand_u32(struct fastrand *c);
  76
  77 /** Uniformly generate 64 random bits. **/
  78 u64 fastrand_u64(struct fastrand *c);
  79
  80 /** Uniformly generate [0, 64] random bits. **/
  81 u64 fastrand_bits_u64(struct fastrand *c, uint bits);
  82
  83 /** Uniformly generate [0, 8*sizeof(uint)] random bits. **/
  84 static inline uint fastrand_bits(struct fastrand *c, uint bits)
  85 {
  86   return fastrand_bits_u64(c, bits);
  87 }
  88
  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);
  91
  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);
  94
  95 /** Generate @size random bytes. **/
  96 void fastrand_mem(struct fastrand *c, void *ptr, size_t size);
  97
  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);
 100
 101 #endif