docs: memory sizes with suffixes and HG_MALLOC elastic arenas (4.1)

docs/migration/4-0-0-to-4-1-0.md

@@ -48,6 +48,13 @@ The following is the full list of backwards-incompatible syntax or functional ch
   the framework and `pi_reload` to reload it. The old `pi_reload_tbls_and_cmds`
   / `pi_http:reload_tbls_and_cmds` commands should no longer be used.
 
+* Memory: `-m` and `-M` now also accept a `k`/`m`/`g` suffix and the
+  `INIT:CAP` form; existing values keep working unchanged. `INIT:CAP` is used
+  by the new, opt-in HG_MALLOC allocator (`-a HG_MALLOC`), which also adds
+  optional global parameters (`shm_auto_scaling_profile`,
+  `pkg_auto_scaling_profile`, `shm_grow_granule`, `pkg_grow_granule` and the
+  `hg_*` parameters). Nothing changes unless it is selected.
+
 ### Core Variables
 
 * example

docs/troubleshooting/increasemem.md

@@ -55,3 +55,21 @@ opensips -m 256
 # this will run OpenSIPS with 256MB of share memory
 
 ```
+
+---
+
+## Let the memory grow (OpenSIPS 4.1 and later)
+
+With the HG_MALLOC allocator both sizes can be given as `INIT:CAP`: OpenSIPS
+starts with INIT and grows on demand up to CAP, so a pool no longer has to be
+sized for the worst case up front:
+
+```bash
+
+opensips -a HG_MALLOC -m 256:2g -M 8:32
+
+# 256 MB of shared memory growing up to 2 GB, 8 MB of private memory per process growing up to 32 MB
+
+```
+
+See [Out Of Memory](/troubleshooting/outofmem#let-the-pool-grow-opensips-41-and-later) for monitoring and host requirements.

docs/troubleshooting/outofmem.md

@@ -35,7 +35,7 @@ If the result is inconclusive, continue with the memory-debugging procedure.
 
 Use the `-m` option to increase the shared-memory pool and the `-M` option to
 increase the private-memory pool allocated to each OpenSIPS process. Both values
-are specified in MB.
+are specified in MB (from OpenSIPS 4.1 they also take a `k`/`m`/`g` suffix).
 
 For example:
 
@@ -50,6 +50,24 @@ installation before restarting OpenSIPS by editing:
 * `/etc/sysconfig/opensips` on Red Hat-based systems
 
 
+### Let the pool grow (OpenSIPS 4.1 and later)
+
+With the HG_MALLOC allocator the pools can be elastic: `-m INIT:CAP` starts at
+INIT, grows on demand up to CAP and gives memory back when it is no longer
+used, so the size does not have to be guessed for the busiest hour:
+
+```bash
+opensips -a HG_MALLOC -m 128:1024 -M 8:32
+```
+
+HG_MALLOC pins its memory: run OpenSIPS with `LimitMEMLOCK=infinity` (or
+`ulimit -l unlimited`) - required for an elastic arena on hugetlb pages, and
+it keeps the arena from being swapped on the others. `opensips-cli -x mi core:hg_advise` reports what `-m` and `-M`
+should be from the peaks actually reached, and the `hgmem:hg_shm_grow_blocked`
+and `hgmem:hg_pkg_grow_blocked` statistics show when an arena cannot grow any
+further. See the HG_MALLOC documentation (`mem/README.hg_malloc.md` in the
+source tree) for details.
+
 ## Debug memory usage on OpenSIPS 3.x and later
 
 ### 1. Enable memory debugging