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 #endif
  28
  29 /* random-fast.c */
  30
  31 /**
  32  * Context structure for a fast pseudo-random generator.
  33  * Useful for generating numbers in randomized algorithms, but not in critical things like cryptography.
  34  * The library is generally thread-safe, but each context must be used by at most one thread at one time.
  35  * Also be careful with fork() if you want to avoid the same numbers in subprocesses.
  36  **/
  37 struct fastrand;
  38
  39 /**
  40  * Type for a seed value. Beware that some generators are only able to use the lowest 32 bits.
  41  **/
  42 typedef u64 fastrand_seed_t;
  43
  44 /**
  45  * Allocate a new context. Should be paired with fastrand_delete().
  46  * Don't forget to supply a seed before started to read randomness.
  47  **/
  48 struct fastrand *fastrand_new(void);
  49 void fastrand_delete(struct fastrand *c);
  50
  51 /** (Re)seed the context with given value. **/
  52 void fastrand_set_seed(struct fastrand *c, fastrand_seed_t seed);
  53
  54 /**
  55  * Generate a seed for fastrand_set_seed().
  56  *
  57  * We currently mix these things (you can add more if needed):
  58  * -- current time
  59  * -- process id to deal with frequent fork() or startups
  60  * -- counter to deal with multiple contexts, for example in threaded application
  61  **/
  62 fastrand_seed_t fastrand_gen_seed_value(void);
  63
  64 /** (Re)seed the context with fastrand_gen_seed_value(). **/
  65 fastrand_seed_t fastrand_gen_seed(struct fastrand *c);
  66
  67 /** Is the context seeded? **/
  68 bool fastrand_has_seed(struct fastrand *c);
  69
  70 /** Reset the context to its initial state. Useful after a fork() to assert forgotten reseed. **/
  71 void fastrand_reset(struct fastrand *c);
  72
  73 /** Uniformly generate 32 random bits. **/
  74 u32 fastrand_u32(struct fastrand *c);
  75
  76 /** Uniformly generate 64 random bits. **/
  77 u64 fastrand_u64(struct fastrand *c);
  78
  79 /** Uniformly generate [0, 64] random bits. **/
  80 u64 fastrand_bits_u64(struct fastrand *c, uint bits);
  81
  82 /** Uniformly generate [0, 8*sizeof(uint)] random bits. **/
  83 static inline uint fastrand_bits(struct fastrand *c, uint bits)
  84 {
  85   return fastrand_bits_u64(c, bits);
  86 }
  87
  88 /** Uniformly generate a random number from range [0, bound-1], where @bound is [1, UINT_MAX]. **/
  89 uint fastrand_max(struct fastrand *c, uint bound);
  90
  91 /** Uniformly generate a random number from range [0, bound-1], where @bound is [1, UINT64_MAX]. **/
  92 u64 fastrand_max_u64(struct fastrand *c, u64 bound);
  93
  94 /** Generate @size random bytes. **/
  95 void fastrand_mem(struct fastrand *c, void *ptr, size_t size);
  96
  97 #endif