src/include/common/pg_prng.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * Pseudo-Random Number Generator
   4  *
   5  * Copyright (c) 2021-2024, PostgreSQL Global Development Group
   6  *
   7  * src/include/common/pg_prng.h
   8  *
   9  *-------------------------------------------------------------------------
  10  */
  11 #ifndef PG_PRNG_H
  12 #define PG_PRNG_H
  13
  14 /*
  15  * State vector for PRNG generation.  Callers should treat this as an
  16  * opaque typedef, but we expose its definition to allow it to be
  17  * embedded in other structs.
  18  */
  19 typedef struct pg_prng_state
  20 {
  21         uint64          s0,
  22                                 s1;
  23 } pg_prng_state;
  24
  25 /*
  26  * Callers not needing local PRNG series may use this global state vector,
  27  * after initializing it with one of the pg_prng_...seed functions.
  28  */
  29 extern PGDLLIMPORT pg_prng_state pg_global_prng_state;
  30
  31 extern void pg_prng_seed(pg_prng_state *state, uint64 seed);
  32 extern void pg_prng_fseed(pg_prng_state *state, double fseed);
  33 extern bool pg_prng_seed_check(pg_prng_state *state);
  34
  35 /*
  36  * Initialize the PRNG state from the pg_strong_random source,
  37  * taking care that we don't produce all-zeroes.  If this returns false,
  38  * caller should initialize the PRNG state from some other random seed,
  39  * using pg_prng_[f]seed.
  40  *
  41  * We implement this as a macro, so that the pg_strong_random() call is
  42  * in the caller.  If it were in pg_prng.c, programs using pg_prng.c
  43  * but not needing strong seeding would nonetheless be forced to pull in
  44  * pg_strong_random.c and thence OpenSSL.
  45  */
  46 #define pg_prng_strong_seed(state) \
  47         (pg_strong_random((void *) (state), sizeof(pg_prng_state)) ? \
  48          pg_prng_seed_check(state) : false)
  49
  50 extern uint64 pg_prng_uint64(pg_prng_state *state);
  51 extern uint64 pg_prng_uint64_range(pg_prng_state *state, uint64 rmin, uint64 rmax);
  52 extern int64 pg_prng_int64(pg_prng_state *state);
  53 extern int64 pg_prng_int64p(pg_prng_state *state);
  54 extern int64 pg_prng_int64_range(pg_prng_state *state, int64 rmin, int64 rmax);
  55 extern uint32 pg_prng_uint32(pg_prng_state *state);
  56 extern int32 pg_prng_int32(pg_prng_state *state);
  57 extern int32 pg_prng_int32p(pg_prng_state *state);
  58 extern double pg_prng_double(pg_prng_state *state);
  59 extern double pg_prng_double_normal(pg_prng_state *state);
  60 extern bool pg_prng_bool(pg_prng_state *state);
  61
  62 #endif                                                  /* PG_PRNG_H */