mem: HG_MALLOC - module arenas: memory a module asks for and HG manages

A module whose memory has nothing to do with transactions - a cache with
its own lifetime, class mix and growth - can now ask for an arena of its
own instead of carving chunks out of shm and managing them itself:

    #include "mem/mem_arena.h"
    mem_arena_t *a = shm_arena_create("cachedb_perf", init, cap);  /* mod_init */
    shm_arena_set_profile(a, "CACHE_PROFILE");                     /* optional */
    p = mem_arena_malloc(a, size);  mem_arena_free(a, p);

The arena is an HG block like shm: slab classes with the per-process
caches, block GC and cross-class re-typing, elastic growth and shrink
within its own INIT:CAP, the maintenance process, its own hg_stats
section and lock histograms. It is created before the fork so every
child inherits the one shared mapping, independent of which allocator
-a selected for the core; the ownership registry routes a free to
whichever arena owns the pointer. The maintenance process now ticks
every registered shared elastic arena rather than the shm block alone,
hg_stats lists module arenas by name, and a process keeps cache state
for up to eight arenas. With no HG_MALLOC compiled in the facade returns
NULL and a module falls back to its own scheme.

Author: Lt-Flash

mem/README.hg_malloc_v3.md

@@ -724,6 +724,29 @@ tune thresholds against the advice lines, flip to 0.
 
 ---
 
+## 11b. Module arenas — memory a module asks for and HG manages
+
+A module whose memory has nothing to do with transactions — a cache with
+its own lifetime, class mix and growth — can ask for an arena of its own
+instead of carving chunks out of shm and managing them itself:
+
+```c
+#include "../../mem/mem_arena.h"
+mem_arena_t *a = shm_arena_create("cachedb_perf", init_bytes, cap_bytes); /* mod_init only */
+shm_arena_set_profile(a, "CACHE_PROFILE");     /* optional: the Section 10 grammar */
+p = mem_arena_malloc(a, size);  mem_arena_free(a, p);
+```
+
+The arena is an HG block like shm — slab classes, per-process caches,
+block GC and cross-class re-typing, elastic growth and shrink within its
+own `INIT:CAP`, the maintenance process (which ticks every registered
+shared arena), its own section in `hg_stats` and its own lock
+histograms — created before the fork so every child inherits the one
+shared mapping, independent of which allocator `-a` selected for the
+core. The ownership registry routes a free to whichever arena owns the
+pointer. With no HG_MALLOC compiled in, `shm_arena_create()` returns
+NULL and the module falls back to its own scheme. Up to 8 arenas.
+
 ## 12. pkg arenas — what is different
 
 * **Per-child, post-config.** Each worker's private arena is created at

mem/hg_arena.c

@@ -147,7 +147,7 @@ static const unsigned int cell_sizes[HG_NCLASSES] = {
  * its own dead TLS rather than returning them - harmless here, because the
  * IO pool threads live for the lifetime of the process.
  */
-#define HG_MAX_INSTANCES 4
+#define HG_MAX_INSTANCES 8   /* shm, pkg, shm_dbg + module arenas */
 static __thread struct hg_palloc palloc_slots[HG_MAX_INSTANCES];
 
 /*

mem/hg_maint.c

@@ -46,6 +46,7 @@
 #ifdef HG_MALLOC
 
 #include <unistd.h>
+#include <string.h>
 
 #include "../dprint.h"
 #include "../globals.h"
@@ -61,17 +62,26 @@
 #define HG_MAINT_TICK_MS     1000
 #define HG_MAINT_SLOW_TICKS  30     /* profile + shrink cadence, in ticks */
 
-static struct hg_block *maint_hb;
 static unsigned long maint_last_ns;
 static unsigned int maint_ticks;
 
+/* a shared arena with a cap above its initial size: the shm arena under
+ * -a HG_MALLOC with -m INIT:CAP, or any module arena (hg_arena_create) -
+ * the registry has them all, and module arenas exist before the process
+ * count (modules initialise first) */
+static int maint_arena(const struct hg_block *hb)
+{
+	return hb && hb->shared && hb->buddy_ready && hb->hcap > hb->hsize_min;
+}
+
 static int hg_maint_wanted(void)
 {
-	if (mem_allocator_shm != MM_HG_MALLOC &&
-	    mem_allocator_shm != MM_HG_MALLOC_DBG)
-		return 0;
-	/* a cap above the initial size is what makes the arena elastic */
-	return hg_shm_cap_bytes > (unsigned long)shm_mem_size;
+	int i;
+
+	for (i = 0; i < HG_ARENA_REG_MAX; i++)
+		if (maint_arena(hg_arena_reg[i].hb))
+			return 1;
+	return 0;
 }
 
 int hg_maint_count_processes(void)
@@ -81,23 +91,30 @@ int hg_maint_count_processes(void)
 
 static void hg_maint_tick(void)
 {
-	struct hg_block *hb = maint_hb;
 	unsigned long now = hg_now_ns();
+	int i, slow;
 
 	/* the reactor returns on every IPC job too; tick once a second */
-	if (!hb || !hb->buddy_ready ||
-	    now - maint_last_ns < (unsigned long)HG_MAINT_TICK_MS * 1000000UL)
+	if (now - maint_last_ns < (unsigned long)HG_MAINT_TICK_MS * 1000000UL)
 		return;
 	maint_last_ns = now;
-
-	hg_lock_enter(hb, HG_LK_POLICY);
-	hg_grow_headroom_tick(hb);
-	if (++maint_ticks >= HG_MAINT_SLOW_TICKS) {
+	slow = (++maint_ticks >= HG_MAINT_SLOW_TICKS);
+	if (slow)
 		maint_ticks = 0;
-		hg_grow_tick(hb);
-		hg_shrink_tick(hb);
+
+	for (i = 0; i < HG_ARENA_REG_MAX; i++) {
+		struct hg_block *hb = hg_arena_reg[i].hb;
+
+		if (!maint_arena(hb))
+			continue;
+		hg_lock_enter(hb, HG_LK_POLICY);
+		hg_grow_headroom_tick(hb);
+		if (slow) {
+			hg_grow_tick(hb);
+			hg_shrink_tick(hb);
+		}
+		hg_lock_leave(hb);
 	}
-	hg_lock_leave(hb);
 }
 
 inline static int handle_io(struct fd_map *fm, int idx, int event_type)
@@ -137,7 +154,6 @@ int hg_maint_start(void)
 
 	/* the child */
 	clean_write_pipeend();
-	maint_hb = (struct hg_block *)shm_block;
 	if (init_worker_reactor("HG_maintenance", RCT_PRIO_MAX) < 0) {
 		LM_ERR("failed to init the maintenance reactor\n");
 		goto error;
@@ -146,20 +162,42 @@ int hg_maint_start(void)
 		LM_CRIT("failed to add the IPC pipe to the maintenance reactor\n");
 		goto error;
 	}
-	maint_hb->maint_proc = process_no;
-	__atomic_store_n(&maint_hb->maint_active, 1, __ATOMIC_RELEASE);
-	maint_last_ns = hg_now_ns();
-	LM_NOTICE("HG maintenance process started: %s arena grows ahead of "
-		"demand here (headroom tick every %d ms, policy every %d ticks), "
-		"the sweep's proactive ticks stand down\n", maint_hb->name,
-		HG_MAINT_TICK_MS, HG_MAINT_SLOW_TICKS);
+	{
+		int i;
+		char names[256] = "";
+
+		for (i = 0; i < HG_ARENA_REG_MAX; i++) {
+			struct hg_block *hb = hg_arena_reg[i].hb;
+
+			if (!maint_arena(hb))
+				continue;
+			hb->maint_proc = process_no;
+			__atomic_store_n(&hb->maint_active, 1, __ATOMIC_RELEASE);
+			if (strlen(names) + strlen(hb->name) + 2 < sizeof names) {
+				if (*names)
+					strcat(names, ",");
+				strcat(names, hb->name);
+			}
+		}
+		maint_last_ns = hg_now_ns();
+		LM_NOTICE("HG maintenance process started: arena(s) %s grow ahead "
+			"of demand here (headroom tick every %d ms, policy every %d "
+			"ticks), the sweep's proactive ticks stand down\n", names,
+			HG_MAINT_TICK_MS, HG_MAINT_SLOW_TICKS);
+	}
 
 	reactor_main_loop(HG_MAINT_TICK_MS, error, hg_maint_tick());
 	destroy_worker_reactor();
 error:
 	LM_ERR("the HG maintenance process failed to initialise, exiting\n");
-	if (maint_hb)
-		__atomic_store_n(&maint_hb->maint_active, 0, __ATOMIC_RELEASE);
+	{
+		int i;
+
+		for (i = 0; i < HG_ARENA_REG_MAX; i++)
+			if (maint_arena(hg_arena_reg[i].hb))
+				__atomic_store_n(&hg_arena_reg[i].hb->maint_active, 0,
+					__ATOMIC_RELEASE);
+	}
 	exit(-1);
 }
 

mem/hg_malloc.c

@@ -853,6 +853,15 @@ static void hg_arena_reg_del(struct hg_block *hb)
  */
 struct hg_block *hg_malloc_init(unsigned long size, char *name, int shared,
 		const char *proc_desc, unsigned int flags)
+{
+	/* the core arenas take their cap by name (below); a module arena
+	 * brings its own - see hg_arena_create() */
+	return hg_malloc_init_cap(size, HG_CAP_BY_NAME, name, shared, proc_desc,
+		flags);
+}
+
+struct hg_block *hg_malloc_init_cap(unsigned long size, unsigned long cap_req,
+		char *name, int shared, const char *proc_desc, unsigned int flags)
 {
 	enum hg_mem_tier tier;
 	unsigned long locked_mb;
@@ -872,7 +881,9 @@ struct hg_block *hg_malloc_init(unsigned long size, char *name, int shared,
 	 * they cannot come from the config, which is parsed only after this
 	 * arena exists (and, for tier 1, after the pool reservation is
 	 * already taken). */
-	if (!strcmp(name, "shm"))
+	if (cap_req != HG_CAP_BY_NAME)
+		cap = cap_req;
+	else if (!strcmp(name, "shm"))
 		cap = hg_shm_cap_bytes;
 	else if (!strcmp(name, "pkg"))
 		cap = hg_pkg_cap_bytes;
@@ -1226,3 +1237,79 @@ void hg_status_dbg(struct hg_block *hb)
 #endif
 
 #endif /* HG_MALLOC */
+
+/* --- module arenas ------------------------------------------------------
+ *
+ * A module that wants its own memory - a cache whose lifetime, class mix and
+ * growth have nothing to do with transactions - asks for an arena here and
+ * gets one that HG_MALLOC manages completely: the slab classes with their
+ * per-process caches, block GC and re-typing, elastic growth and shrink
+ * inside the module's own INIT:CAP, the maintenance process (which ticks
+ * every registered shared arena), hg_stats. The arena is created BEFORE the
+ * fork (mod_init), so every child inherits the one shared mapping exactly
+ * as it does the shm arena; the ownership registry routes a free to the
+ * arena that owns the pointer, whichever one it is. Independent of the -a
+ * choice: the core allocator can be anything while the module's cells live
+ * in HG.
+ */
+struct hg_block *hg_arena_create(char *name, unsigned long init_bytes,
+		unsigned long cap_bytes)
+{
+	struct hg_block *hb;
+	int i, free_slot = -1;
+
+	if (!name || !*name) {
+		LM_ERR("module arena needs a name\n");
+		return NULL;
+	}
+	if (init_bytes < 2 * HG_HPS) {
+		LM_ERR("module arena '%s': %lu MB is below the %lu MB minimum "
+			"viable arena\n", name, init_bytes >> 20, (2 * HG_HPS) >> 20);
+		return NULL;
+	}
+	if (cap_bytes < init_bytes)
+		cap_bytes = init_bytes;
+	for (i = 0; i < HG_ARENA_REG_MAX; i++) {
+		if (hg_arena_reg[i].hb && hg_arena_reg[i].hb->name &&
+		    !strcmp(hg_arena_reg[i].hb->name, name)) {
+			LM_ERR("module arena '%s' already exists\n", name);
+			return NULL;
+		}
+		if (free_slot < 0 && !hg_arena_reg[i].base)
+			free_slot = i;
+	}
+	if (free_slot < 0) {
+		LM_ERR("module arena '%s': all %d arena slots are taken\n",
+			name, HG_ARENA_REG_MAX);
+		return NULL;
+	}
+
+	hb = hg_malloc_init_cap(init_bytes, HG_HPS_ROUND(cap_bytes), name, 1,
+		NULL, 0);
+	if (!hb) {
+		LM_ERR("module arena '%s': could not reserve %lu MB (cap %lu MB)\n",
+			name, init_bytes >> 20, cap_bytes >> 20);
+		return NULL;
+	}
+	LM_NOTICE("module arena '%s': %lu MB committed, can grow to %lu MB - "
+		"managed by HG_MALLOC (classes, GC, growth, maintenance)\n",
+		name, hb->hsize >> 20, hb->hcap >> 20);
+	return hb;
+}
+
+/* attach an auto_scaling_profile to a module arena (mod_init, pre-fork) */
+int hg_arena_set_profile(struct hg_block *hb, const char *profile_name)
+{
+	struct scaling_profile *p;
+
+	if (!hb || !profile_name)
+		return -1;
+	p = get_scaling_profile((char *)profile_name);
+	if (!p) {
+		LM_ERR("arena '%s': '%s' does not name an auto_scaling_profile\n",
+			hb->name, profile_name);
+		return -1;
+	}
+	return hg_autoscale_apply(hb, hb->name, p, hb->hsize_min, hb->hcap);
+}
+

mem/hg_malloc.h

@@ -1232,6 +1232,16 @@ unsigned long hg_slab_recycled(struct hg_block *hb);
  */
 #ifdef HG_MALLOC
 int hg_register_stats(void);
+
+/* --- module arenas (see hg_arena_create() in hg_malloc.c) --------------- */
+#define HG_CAP_BY_NAME (~0UL)   /* hg_malloc_init_cap: take the cap from -m/-M */
+struct hg_block *hg_malloc_init_cap(unsigned long size, unsigned long cap_req,
+		char *name, int shared, const char *proc_desc, unsigned int flags);
+/* a shared, elastic arena of the module's own; @name must outlive the block;
+ * pre-fork only. NULL = refused (logged) */
+struct hg_block *hg_arena_create(char *name, unsigned long init_bytes,
+		unsigned long cap_bytes);
+int hg_arena_set_profile(struct hg_block *hb, const char *profile_name);
 #else
 /* No-op without the allocator, so callers (statistics.c) need no #ifdef of
  * their own. Building with -DHG_MALLOC removed previously failed at link with