[6.0] afd267dc3 document umem specifics

[Dridi Boukelmoune]

commit afd267dc3feb8f79bed94b05a0cbd64797fdb01a
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Wed Apr 4 16:47:45 2018 +0200

    document umem specifics

diff --git a/doc/sphinx/reference/varnishd.rst b/doc/sphinx/reference/varnishd.rst
index b6d383a75..de7ee866f 100644
--- a/doc/sphinx/reference/varnishd.rst
+++ b/doc/sphinx/reference/varnishd.rst
@@ -320,6 +320,9 @@ The following storage types are available:
   umem is a storage backend which is more efficient than malloc on
   platforms where it is available.
 
+  See the section on umem in chapter `Storage backends` of `The
+  Varnish Users Guide` for details.
+
 -s <file,path[,size[,granularity[,advice]]]>
 
   The file backend stores data in a file on disk. The file will be
diff --git a/doc/sphinx/users-guide/storage-backends.rst b/doc/sphinx/users-guide/storage-backends.rst
index a6311066f..3dd71408a 100644
--- a/doc/sphinx/users-guide/storage-backends.rst
+++ b/doc/sphinx/users-guide/storage-backends.rst
@@ -53,6 +53,8 @@ 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.
 
+.. _guide-storage_umem:
+
 umem
 ~~~~
 
@@ -69,6 +71,37 @@ implementations. In particular, `libumem`_ is included in the family
 of OpenSolaris descendent operating systems where jemalloc(3) is not
 commonly available.
 
+If `libumem`_ is not used otherwise, varnish will only use it for
+storage allocations and keep the default libc allocator for all other
+varnish memory allocation purposes.
+
+If `libumem`_ is already loaded when varnish initializes, this message
+is output::
+
+  notice: libumem was already found to be loaded
+          and will likely be used for all allocations
+
+to indicate that `libumem`_ will not only be used for storage. Likely
+reasons for this to be the case are:
+
+* some library ``varnishd`` is linked against was linked against
+  `libumem`_ (most likely ``libpcre``, check with ``ldd``)
+
+* ``LD_PRELOAD_64=/usr/lib/amd64/libumem.so.1``,
+  ``LD_PRELOAD_32=/usr/lib/libumem.so.1`` or
+  ``LD_PRELOAD=/usr/lib/libumem.so.1`` is set
+
+varnish will also output this message to recommend settings for using
+`libumem`_ for all allocations::
+
+  it is recommended to set UMEM_OPTIONS=perthread_cache=0,backend=mmap
+  before starting varnish
+
+This recommendation should be followed to achieve an optimal
+`libumem`_ configuration for varnish. Setting this environment
+variable before starting varnish is required becuase `libumem`_ cannot
+be reconfigured once loaded.
+
 .. _libumem: http://dtrace.org/blogs/ahl/2004/07/13/number-11-of-20-libumem/
 
 file