Refactor deferral constants into corresponding headers.

Currently there are deferral-relevant constants in arena.c and
background_thread.c. This commit moves them out into corresponding PAC
and HPA headers. Those commonly needed by both are put into a new header
deferral.h where the contract of deferral are clearly stated.

include/jemalloc/internal/arena.h

@@ -177,12 +177,6 @@ struct arena_s {
 /* EXTERNS */
 /******************************************************************************/
 
-/*
- * When the amount of pages to be purged exceeds this amount, deferred purge
- * should happen.
- */
-#define ARENA_DEFERRED_PURGE_NPAGES_THRESHOLD UINT64_C(1024)
-
 extern ssize_t opt_dirty_decay_ms;
 extern ssize_t opt_muzzy_decay_ms;
 

include/jemalloc/internal/background_thread.h

@@ -13,17 +13,6 @@
 #define MAX_BACKGROUND_THREAD_LIMIT MALLOCX_ARENA_LIMIT
 #define DEFAULT_NUM_BACKGROUND_THREAD 4
 
-/*
- * These exist only as a transitional state.  Eventually, deferral should be
- * part of the PAI, and each implementation can indicate wait times with more
- * specificity.
- */
-#define BACKGROUND_THREAD_HPA_INTERVAL_MAX_UNINITIALIZED (-2)
-#define BACKGROUND_THREAD_HPA_INTERVAL_MAX_DEFAULT_WHEN_ENABLED 5000
-
-#define BACKGROUND_THREAD_DEFERRED_MIN UINT64_C(0)
-#define BACKGROUND_THREAD_DEFERRED_MAX UINT64_MAX
-
 typedef enum {
 	background_thread_stopped,
 	background_thread_started,

include/jemalloc/internal/deferral.h

@@ -0,0 +1,30 @@
+#ifndef JEMALLOC_INTERNAL_DEFERRAL_H
+#define JEMALLOC_INTERNAL_DEFERRAL_H
+
+#include "jemalloc/internal/jemalloc_preamble.h"
+
+/*
+ * The deferred-work contract shared by the page allocators that PRODUCE
+ * deferred work (PAC decay-purge, HPA purge/hugify) and the drivers that
+ * CONSUME it (the background thread, or the application-inline fallback).
+ *
+ * There is deliberately no polymorphic interface here: with only two
+ * page allocators, a vtable's indirect calls are needless and inefficient.
+ * Dispatch is direct pac_*()/hpa_*(), so the contract is a convention
+ * documented here, not an enforced type.  The only shared code it needs is the
+ * constants below; each allocator keeps its own policy definition (functions
+ * and constants) in its own header.
+ *
+ * The convention every page allocator follows:
+ *   - <alloc>_time_until_deferred_work(): nanoseconds until its next
+ *     deferred work is due.  DEFERRED_WORK_MIN = "due now",
+ *     DEFERRED_WORK_MAX = "nothing pending"; anything between is a real
+ *     ns deadline.
+ *   - <alloc>_do_deferred_work(): perform whatever work is due now.
+ * The pa layer reports the soonest deadline across its allocators; the
+ * background thread sleeps until then, or indefinitely on DEFERRED_WORK_MAX.
+ */
+#define DEFERRED_WORK_MIN UINT64_C(0)
+#define DEFERRED_WORK_MAX UINT64_MAX
+
+#endif /* JEMALLOC_INTERNAL_DEFERRAL_H */

include/jemalloc/internal/hpa.h

@@ -13,6 +13,14 @@
 #include "jemalloc/internal/psset.h"
 #include "jemalloc/internal/sec.h"
 
+/*
+ * HPA-specific deferral interval bounds (currently unused).  Deferral tuning
+ * is per-allocator policy, so it lives in the HPA header; see deferral.h for
+ * the shared deferred-work contract.
+ */
+#define HPA_INTERVAL_MAX_UNINITIALIZED (-2)
+#define HPA_INTERVAL_MAX_DEFAULT_WHEN_ENABLED 5000
+
 typedef struct hpa_shard_nonderived_stats_s hpa_shard_nonderived_stats_t;
 struct hpa_shard_nonderived_stats_s {
 	/*

include/jemalloc/internal/pac.h

@@ -13,7 +13,7 @@
 #include "san_bump.h"
 
 /*
- * Page allocator classic; an implementation of the PAI interface that:
+ * Page allocator classic (PAC), a page-level allocator that:
  * - Can be used for arenas with custom extent hooks.
  * - Can always satisfy any allocation request (including highly-fragmentary
  *   ones).
@@ -28,6 +28,14 @@ enum pac_purge_eagerness_e {
 };
 typedef enum pac_purge_eagerness_e pac_purge_eagerness_t;
 
+/*
+ * When a decay sweep would purge more than this many pages, its purge is
+ * treated as due (worth waking the background thread for) instead of left
+ * to accumulate.  PAC decay policy; the HPA defers on time intervals, not
+ * on a page count, so this constant is PAC-only.
+ */
+#define PAC_DECAY_PURGE_NPAGES_THRESHOLD UINT64_C(1024)
+
 typedef struct pac_decay_stats_s pac_decay_stats_t;
 struct pac_decay_stats_s {
 	/* Total number of purge sweeps. */