[master] 40f4366fa doc: Mention known malloc stevedore issues more clearly

[Nils Goroll]

commit 40f4366fa3045f53ed0b8e0aba4b2f56a9c4136a
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Thu Feb 6 21:03:32 2025 +0100

    doc: Mention known malloc stevedore issues more clearly
    
    Closes #3965

diff --git a/doc/sphinx/installation/platformnotes.rst b/doc/sphinx/installation/platformnotes.rst
index 012095fa3..371105ffb 100644
--- a/doc/sphinx/installation/platformnotes.rst
+++ b/doc/sphinx/installation/platformnotes.rst
@@ -53,6 +53,8 @@ size of *workdir* when varnish is running.
 
 See :ref:`ref-vsm` for details.
 
+.. _platform-thp:
+
 Transparent hugepages on Redhat Enterprise Linux 6
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/sphinx/users-guide/sizing-your-cache.rst b/doc/sphinx/users-guide/sizing-your-cache.rst
index 20189474c..c3375e87c 100644
--- a/doc/sphinx/users-guide/sizing-your-cache.rst
+++ b/doc/sphinx/users-guide/sizing-your-cache.rst
@@ -23,10 +23,5 @@ Deciding on cache size can be a tricky task. A few things to consider:
    evicting objects due to space constraints and you should consider
    increasing the size of the cache.
 
-Be aware that every object that is stored also carries overhead that
-is kept outside the actually storage area. So, even if you specify ``-s
-malloc,16G`` Varnish might actually use **double** that. Varnish has a
-overhead of about 1KB per object. So, if you have lots of small objects
-in your cache the overhead might be significant.
-
-.. XXX:This seems to contradict the last paragraph in "storage-backends". benc
+Also, there are additional considerations for specific storage engines
+(stevedores), see :ref:`guide-storage` for details.
diff --git a/doc/sphinx/users-guide/storage-backends.rst b/doc/sphinx/users-guide/storage-backends.rst
index 36014ff81..0030461d9 100644
--- a/doc/sphinx/users-guide/storage-backends.rst
+++ b/doc/sphinx/users-guide/storage-backends.rst
@@ -25,6 +25,11 @@ objects, the rule of thumb is *n* x ``transit_buffer``.
 
 Storage backends are also called stevedores.
 
+.. _vmods: https://www.varnish-cache.org/vmods
+
+Besides the built-in storage backends, separately distributed extensions exist,
+which can be found on the `vmods`_ page by searching for "stevedore".
+
 default
 ~~~~~~~
 
@@ -38,18 +43,13 @@ malloc
 
 syntax: malloc[,size]
 
-Malloc is a memory based backend. Each object will be allocated from
-memory. If your system runs low on memory swap will be used.
-
-Be aware that the size limitation only limits the actual storage and that the
-approximately 1k of memory per object, used for various internal
-structures, is included in the actual storage as well.
+Malloc is a virtual memory based storage backend. Each object will be allocated
+using whatever ``malloc()`` implementation is in effect. If configured, virtual
+memory might get paged in and out to swap space by the operating system.
 
-.. XXX:This seems to contradict the last paragraph in "sizing-your-cache". benc
-
-The size parameter specifies the maximum amount of memory `varnishd`
-will allocate.  The size is assumed to be in bytes, unless followed by
-one of the following suffixes:
+The size parameter specifies the maximum *net* amount of memory `varnishd` will
+allocate.  The size is assumed to be in bytes, unless followed by one of the
+following suffixes:
 
       K, k    The size is expressed in kibibytes.
 
@@ -61,9 +61,21 @@ one of the following suffixes:
 
 The default size is unlimited.
 
-malloc's performance is bound to memory speed so it is very fast. If
-the dataset is bigger than available memory performance will
-depend on the operating systems ability to page effectively.
+The *net* amount of memory comprises object metadata (typically in the order of
+the total size of headers), segmented body data and metadata for the storage
+engine itself.
+
+This *net* amount of memory is the sum of all allocation sizes from the
+perspective of `varnishd`, but for the actual *gross* amount, two additional
+factors need to be considered: `varnishd` also requires memory outside the
+storage engine in the order of 1KB per object. And, more importantly, due to
+fragmentation, the amount of memory actually used by the malloc implementation
+might be substantially higher by a factor of typically **two to four times**.
+Specific optimizations like :ref:`platform-thp` can amplify this effect.
+
+malloc's performance is bound to memory speed, so it is very fast. If
+the dataset is bigger than available memory, performance will
+depend on the operating system's ability to page effectively.
 
 .. _guide-storage_umem: