From fa3ad730c492c50f19fc68050ea5d5175b1df3cb Mon Sep 17 00:00:00 2001
From: David Goldblatt <davidgoldblatt@fb.com>
Date: Wed, 19 Apr 2017 12:48:50 -0700
Subject: [PATCH] Header refactoring: prng module - remove from the catchall
 and unify.

---
 include/jemalloc/internal/extent_inlines.h    |  1 +
 .../internal/jemalloc_internal_includes.h     |  2 -
 .../internal/{prng_inlines.h => prng.h}       | 50 +++++++++++++++++--
 include/jemalloc/internal/prng_types.h        | 29 -----------
 include/jemalloc/internal/prof_structs.h      |  1 +
 src/ckh.c                                     |  1 +
 6 files changed, 49 insertions(+), 35 deletions(-)
 rename include/jemalloc/internal/{prng_inlines.h => prng.h} (65%)
 delete mode 100644 include/jemalloc/internal/prng_types.h

diff --git a/include/jemalloc/internal/extent_inlines.h b/include/jemalloc/internal/extent_inlines.h
index 22d45ce1..a73b6530 100644
--- a/include/jemalloc/internal/extent_inlines.h
+++ b/include/jemalloc/internal/extent_inlines.h
@@ -1,6 +1,7 @@
 #ifndef JEMALLOC_INTERNAL_EXTENT_INLINES_H
 #define JEMALLOC_INTERNAL_EXTENT_INLINES_H
 
+#include "jemalloc/internal/prng.h"
 #include "jemalloc/internal/ql.h"
 
 static inline arena_t *
diff --git a/include/jemalloc/internal/jemalloc_internal_includes.h b/include/jemalloc/internal/jemalloc_internal_includes.h
index 669194d0..5e80f96c 100644
--- a/include/jemalloc/internal/jemalloc_internal_includes.h
+++ b/include/jemalloc/internal/jemalloc_internal_includes.h
@@ -40,7 +40,6 @@
 /* TYPES */
 /******************************************************************************/
 
-#include "jemalloc/internal/prng_types.h"
 #include "jemalloc/internal/ticker_types.h"
 #include "jemalloc/internal/ckh_types.h"
 #include "jemalloc/internal/size_classes.h"
@@ -108,7 +107,6 @@
 /* INLINES */
 /******************************************************************************/
 
-#include "jemalloc/internal/prng_inlines.h"
 #include "jemalloc/internal/ticker_inlines.h"
 #include "jemalloc/internal/tsd_inlines.h"
 #include "jemalloc/internal/witness_inlines.h"
diff --git a/include/jemalloc/internal/prng_inlines.h b/include/jemalloc/internal/prng.h
similarity index 65%
rename from include/jemalloc/internal/prng_inlines.h
rename to include/jemalloc/internal/prng.h
index 0275dfc4..15cc2d18 100644
--- a/include/jemalloc/internal/prng_inlines.h
+++ b/include/jemalloc/internal/prng.h
@@ -1,9 +1,37 @@
-#ifndef JEMALLOC_INTERNAL_PRNG_INLINES_H
-#define JEMALLOC_INTERNAL_PRNG_INLINES_H
+#ifndef JEMALLOC_INTERNAL_PRNG_H
+#define JEMALLOC_INTERNAL_PRNG_H
 
 #include "jemalloc/internal/atomic.h"
 #include "jemalloc/internal/bit_util.h"
 
+/*
+ * Simple linear congruential pseudo-random number generator:
+ *
+ *   prng(y) = (a*x + c) % m
+ *
+ * where the following constants ensure maximal period:
+ *
+ *   a == Odd number (relatively prime to 2^n), and (a-1) is a multiple of 4.
+ *   c == Odd number (relatively prime to 2^n).
+ *   m == 2^32
+ *
+ * See Knuth's TAOCP 3rd Ed., Vol. 2, pg. 17 for details on these constraints.
+ *
+ * This choice of m has the disadvantage that the quality of the bits is
+ * proportional to bit position.  For example, the lowest bit has a cycle of 2,
+ * the next has a cycle of 4, etc.  For this reason, we prefer to use the upper
+ * bits.
+ */
+
+/******************************************************************************/
+/* INTERNAL DEFINITIONS -- IGNORE */
+/******************************************************************************/
+#define PRNG_A_32	UINT32_C(1103515241)
+#define PRNG_C_32	UINT32_C(12347)
+
+#define PRNG_A_64	UINT64_C(6364136223846793005)
+#define PRNG_C_64	UINT64_C(1442695040888963407)
+
 JEMALLOC_ALWAYS_INLINE uint32_t
 prng_state_next_u32(uint32_t state) {
 	return (state * PRNG_A_32) + PRNG_C_32;
@@ -25,6 +53,16 @@ prng_state_next_zu(size_t state) {
 #endif
 }
 
+/******************************************************************************/
+/* BEGIN PUBLIC API */
+/******************************************************************************/
+
+/*
+ * The prng_lg_range functions give a uniform int in the half-open range [0,
+ * 2**lg_range).  If atomic is true, they do so safely from multiple threads.
+ * Multithreaded 64-bit prngs aren't supported.
+ */
+
 JEMALLOC_ALWAYS_INLINE uint32_t
 prng_lg_range_u32(atomic_u32_t *state, unsigned lg_range, bool atomic) {
 	uint32_t ret, state0, state1;
@@ -48,7 +86,6 @@ prng_lg_range_u32(atomic_u32_t *state, unsigned lg_range, bool atomic) {
 	return ret;
 }
 
-/* 64-bit atomic operations cannot be supported on all relevant platforms. */
 JEMALLOC_ALWAYS_INLINE uint64_t
 prng_lg_range_u64(uint64_t *state, unsigned lg_range) {
 	uint64_t ret, state1;
@@ -86,6 +123,11 @@ prng_lg_range_zu(atomic_zu_t *state, unsigned lg_range, bool atomic) {
 	return ret;
 }
 
+/*
+ * The prng_range functions behave like the prng_lg_range, but return a result
+ * in [0, range) instead of [0, 2**lg_range).
+ */
+
 JEMALLOC_ALWAYS_INLINE uint32_t
 prng_range_u32(atomic_u32_t *state, uint32_t range, bool atomic) {
 	uint32_t ret;
@@ -140,4 +182,4 @@ prng_range_zu(atomic_zu_t *state, size_t range, bool atomic) {
 	return ret;
 }
 
-#endif /* JEMALLOC_INTERNAL_PRNG_INLINES_H */
+#endif /* JEMALLOC_INTERNAL_PRNG_H */
diff --git a/include/jemalloc/internal/prng_types.h b/include/jemalloc/internal/prng_types.h
deleted file mode 100644
index 3e8e1834..00000000
--- a/include/jemalloc/internal/prng_types.h
+++ /dev/null
@@ -1,29 +0,0 @@
-#ifndef JEMALLOC_INTERNAL_PRNG_TYPES_H
-#define JEMALLOC_INTERNAL_PRNG_TYPES_H
-
-/*
- * Simple linear congruential pseudo-random number generator:
- *
- *   prng(y) = (a*x + c) % m
- *
- * where the following constants ensure maximal period:
- *
- *   a == Odd number (relatively prime to 2^n), and (a-1) is a multiple of 4.
- *   c == Odd number (relatively prime to 2^n).
- *   m == 2^32
- *
- * See Knuth's TAOCP 3rd Ed., Vol. 2, pg. 17 for details on these constraints.
- *
- * This choice of m has the disadvantage that the quality of the bits is
- * proportional to bit position.  For example, the lowest bit has a cycle of 2,
- * the next has a cycle of 4, etc.  For this reason, we prefer to use the upper
- * bits.
- */
-
-#define PRNG_A_32	UINT32_C(1103515241)
-#define PRNG_C_32	UINT32_C(12347)
-
-#define PRNG_A_64	UINT64_C(6364136223846793005)
-#define PRNG_C_64	UINT64_C(1442695040888963407)
-
-#endif /* JEMALLOC_INTERNAL_PRNG_TYPES_H */
diff --git a/include/jemalloc/internal/prof_structs.h b/include/jemalloc/internal/prof_structs.h
index e1936769..82080aa1 100644
--- a/include/jemalloc/internal/prof_structs.h
+++ b/include/jemalloc/internal/prof_structs.h
@@ -1,6 +1,7 @@
 #ifndef JEMALLOC_INTERNAL_PROF_STRUCTS_H
 #define JEMALLOC_INTERNAL_PROF_STRUCTS_H
 
+#include "jemalloc/internal/prng.h"
 #include "jemalloc/internal/rb.h"
 
 struct prof_bt_s {
diff --git a/src/ckh.c b/src/ckh.c
index 6576740b..db52a845 100644
--- a/src/ckh.c
+++ b/src/ckh.c
@@ -40,6 +40,7 @@
 
 #include "jemalloc/internal/assert.h"
 #include "jemalloc/internal/malloc_io.h"
+#include "jemalloc/internal/prng.h"
 #include "jemalloc/internal/util.h"
 
 /******************************************************************************/