mem: add an hg_stats MI command, and document carving

The shared shmem: statistics have six slots, designed for an allocator
where freeing returns memory to one general pool. HG_MALLOC carves the
arena into fixed size-class chunks that are never handed back, so
committed, live and available stop being the same question and the six
slots cannot express the difference.

Rather than overload the shared names further, report the allocator's own
view: which tier the arena got, how much has ever been carved, how much
of that is live versus sitting recycled on a free stack, and the
per-size-class chunk breakdown. pkg arenas are per-process, so that half
reports the arena of whichever process answered.

Document what carving means alongside it, including the two things that
surprise: free_size + real_used_size does not sum to total_size (the
difference is carved-but-idle capacity), and recycled capacity is only
reusable within its own size class.

Author: Lt-Flash

mem/README.hg_malloc

@@ -117,6 +117,86 @@ while the other allocators on the same machine and workload ranged from
 still worth using.
 
 
+Carving, and what the memory statistics mean
+--------------------------------------------
+
+HG_MALLOC does not treat the arena as one pool of interchangeable bytes.
+It CARVES it: the first time a process needs a cell of some size class, a
+whole chunk is cut out of the arena, divided into equal cells of that
+class, and given to that process. A chunk is never handed back. Freeing a
+cell returns it to a per-process free stack, ready to be reused - but only
+for the same size class, and preferentially by the same process.
+
+That single property is why the memory statistics read differently here
+than under q_malloc or f_malloc, where a freed fragment returns to a
+general pool and can serve a request of any size.
+
+    used_size        payload bytes currently handed to callers. Rises and
+                     falls with load; same meaning as everywhere else.
+
+    real_used_size   live commitment - the cell slots currently handed
+                     out, including each cell's header and the round-up to
+                     its size class. Rises and falls with load.
+
+    max_used_size    high-water mark of real_used_size. Climbs to the
+                     working set and then holds, as for the other
+                     allocators.
+
+    free_size        arena not yet carved. This is the figure that
+                     predicts "no more HG_MALLOC arena memory": it counts
+                     down as chunks are cut, and never goes back up.
+
+    fragments        live cells.
+
+Two consequences are worth stating plainly.
+
+First, free_size + real_used_size does not add up to total_size. Under
+q_malloc it does. Here the difference is the carved-but-idle capacity -
+cells sitting on a free stack. They are genuinely reusable, so calling
+them "used" would overstate demand; they are also already committed to one
+size class, so calling them "free" would overstate what is available. The
+identity that does hold is:
+
+    free_size + carved = total_size
+
+Second, recycled capacity is not interchangeable. An arena can report a
+large free_size and still fail an allocation, if what has been carved does
+not match the size being asked for. In practice a given workload settles
+into a stable mix of sizes and this does not arise, but it is the reason
+free_size is defined as "not yet carved" rather than "not in use".
+
+None of this has to be inferred: hg_stats below reports each quantity
+separately.
+
+
+hg_stats
+--------
+
+    opensips-cli -x mi hg_stats
+
+Reports the allocator's own view of each arena it manages: shm, and the
+pkg arena of whichever process answered the command. pkg arenas are
+per-process, so that half is one process's arena, not a server-wide total.
+
+    tier              which of the four huge-page tiers the arena got
+    total_size        arena size, as given by -m / -M
+    pinned_mb         MB protected from swapping
+    carved            bytes ever cut out of the arena into chunks
+    carved_peak       high-water mark of the above
+    chunks            how many chunks that is
+    free_to_carve     total_size - carved, i.e. shmem:free_size
+    live_cell_bytes   cell slots currently handed out
+    live_payload      of which, requested payload, i.e. shmem:used_size
+    live_cells        number of live cells, i.e. shmem:fragments
+    live_peak         high-water mark, i.e. shmem:max_used_size
+    recycled          carved but idle: on a free stack or in the global
+                      pool
+    classes           per size class: cell size, chunk count, total cells
+
+The per-class breakdown is the quickest way to tell whether an arena is
+being carved into the sizes the workload actually asks for.
+
+
 Per-module memory accounting
 ----------------------------
 

mi/mi_core.c

@@ -44,6 +44,10 @@
 #include "../net/net_tcp.h"
 #include "../mem/mem.h"
 #include "../mem/rpm_mem.h"
+#ifdef HG_MALLOC
+#include "../mem/shm_mem.h"
+#include "../mem/hg_malloc.h"
+#endif
 #include "../cachedb/cachedb.h"
 #include "../evi/event_interface.h"
 #include "../ipc.h"
@@ -982,6 +986,146 @@ static mi_response_t *w_reload_routes(const mi_params_t *params,
 
 
 
+#ifdef HG_MALLOC
+/*
+ * HG_MALLOC keeps state the shared shmem:/pkgmem: statistics cannot express.
+ * Those six figures were designed for a free-list allocator, where freed
+ * memory returns to one general pool; HG_MALLOC instead CARVES the arena into
+ * fixed size-class chunks that are never given back, so "how much is
+ * committed", "how much is live" and "how much can still be handed out" stop
+ * being the same question. Rather than overload the shared names further,
+ * report the allocator's own view here.
+ */
+static int hg_stats_one(mi_item_t *parent, char *name, struct hg_block *hb)
+{
+	mi_item_t *o, *cls_arr, *cls_item;
+	struct hg_chunk *ch;
+	unsigned int chunks_of[HG_NCLASSES], cell_size_of[HG_NCLASSES];
+	unsigned long cells_of[HG_NCLASSES];
+	unsigned long carved;
+	const char *tier;
+	int c;
+
+	if (!hb)
+		return 0;
+
+	o = add_mi_object(parent, name, strlen(name));
+	if (!o)
+		return -1;
+
+	carved = hb->real_used;
+	tier = hg_mem_tier_str(hb->tier);
+
+	if (add_mi_string(o, MI_SSTR("tier"), (char *)tier, strlen(tier)) < 0)
+		return -1;
+	if (add_mi_number(o, MI_SSTR("total_size"), hb->size) < 0)
+		return -1;
+	if (add_mi_number(o, MI_SSTR("pinned_mb"), hb->locked_mb) < 0)
+		return -1;
+
+	/* carved: bytes taken from the arena and cut into size-class chunks.
+	 * Never returned - this is the figure that only ever grows, and the one
+	 * that free_size counts down from. */
+	if (add_mi_number(o, MI_SSTR("carved"), carved) < 0)
+		return -1;
+	if (add_mi_number(o, MI_SSTR("carved_peak"), hb->max_real_used) < 0)
+		return -1;
+	if (add_mi_number(o, MI_SSTR("chunks"), hb->nchunks) < 0)
+		return -1;
+	/* what shmem:free_size reports: arena never yet carved */
+	if (add_mi_number(o, MI_SSTR("free_to_carve"), hb->size - carved) < 0)
+		return -1;
+
+	/* live: what is actually handed out right now */
+	if (add_mi_number(o, MI_SSTR("live_cell_bytes"), hg_cell_live(hb)) < 0)
+		return -1;
+	if (add_mi_number(o, MI_SSTR("live_payload"), hg_used(hb)) < 0)
+		return -1;
+	if (add_mi_number(o, MI_SSTR("live_cells"), hg_fragments(hb)) < 0)
+		return -1;
+	if (add_mi_number(o, MI_SSTR("live_peak"), hb->max_live_used) < 0)
+		return -1;
+
+	/* carved but idle: on a private free stack or in the global pool.
+	 * Reusable, but ONLY for its own size class - which is why it is not
+	 * counted as free_to_carve. */
+	if (add_mi_number(o, MI_SSTR("recycled"), hg_slab_recycled(hb)) < 0)
+		return -1;
+
+	memset(chunks_of, 0, sizeof chunks_of);
+	memset(cell_size_of, 0, sizeof cell_size_of);
+	memset(cells_of, 0, sizeof cells_of);
+	for (ch = hb->chunks; ch; ch = ch->next) {
+		if (ch->cls >= HG_NCLASSES)
+			continue;
+		chunks_of[ch->cls]++;
+		cell_size_of[ch->cls] = ch->cell_size;
+		cells_of[ch->cls] += ch->cells;
+	}
+
+	cls_arr = add_mi_array(o, MI_SSTR("classes"));
+	if (!cls_arr)
+		return -1;
+	for (c = 0; c < HG_NCLASSES; c++) {
+		if (!chunks_of[c])
+			continue;
+		cls_item = add_mi_object(cls_arr, 0, 0);
+		if (!cls_item)
+			return -1;
+		if (add_mi_number(cls_item, MI_SSTR("cell_size"),
+			cell_size_of[c]) < 0)
+			return -1;
+		if (add_mi_number(cls_item, MI_SSTR("chunks"), chunks_of[c]) < 0)
+			return -1;
+		if (add_mi_number(cls_item, MI_SSTR("cells"), cells_of[c]) < 0)
+			return -1;
+	}
+
+	return 0;
+}
+
+static mi_response_t *mi_hg_stats(const mi_params_t *params,
+						struct mi_handler *async_hdl)
+{
+	mi_response_t *resp;
+	mi_item_t *resp_obj;
+	int reported = 0;
+
+	resp = init_mi_result_object(&resp_obj);
+	if (!resp)
+		return 0;
+
+	if (mem_allocator_shm == MM_HG_MALLOC ||
+	    mem_allocator_shm == MM_HG_MALLOC_DBG) {
+		if (hg_stats_one(resp_obj, "shm", (struct hg_block *)shm_block) < 0)
+			goto error;
+		reported++;
+	}
+
+	if (mem_allocator_pkg == MM_HG_MALLOC ||
+	    mem_allocator_pkg == MM_HG_MALLOC_DBG) {
+		/* pkg arenas are per-process: this is the arena of whichever
+		 * process answered the command, not a fleet-wide total */
+		if (hg_stats_one(resp_obj, "pkg", (struct hg_block *)mem_block) < 0)
+			goto error;
+		reported++;
+	}
+
+	if (!reported) {
+		free_mi_response(resp);
+		return init_mi_error(400,
+			MI_SSTR("HG_MALLOC is not the active allocator"));
+	}
+
+	return resp;
+
+error:
+	LM_ERR("failed to add mi item\n");
+	free_mi_response(resp);
+	return 0;
+}
+#endif /* HG_MALLOC */
+
 static const mi_export_t mi_core_cmds[] = {
 	{ "pi_list", "lists the provisioning framework", 0, 0, {
 		{w_mi_pi_list, {0}},
@@ -1005,6 +1149,14 @@ static const mi_export_t mi_core_cmds[] = {
 		{mi_pwd, {0}},
 		{EMPTY_MI_RECIPE}}, {0}
 	},
+#ifdef HG_MALLOC
+	{ "hg_stats", "HG_MALLOC arena internals: how much of the arena is "
+		"carved into size-class chunks, how much of that is live versus "
+		"recycled, and the per-class chunk breakdown", 0, 0, {
+		{mi_hg_stats, {0}},
+		{EMPTY_MI_RECIPE}}, {0}
+	},
+#endif
 	{ "arg", "returns the full list of arguments used at startup", 0, 0, {
 		{mi_arg, {0}},
 		{EMPTY_MI_RECIPE}}, {0}