1 files changed, 52 insertions, 0 deletions
diff --git a/security/nss/doc/rst/legacy/memory_allocation/index.rst b/security/nss/doc/rst/legacy/memory_allocation/index.rst
new file mode 100644
index 0000000000..96d9807ee9
--- /dev/null
+++ b/security/nss/doc/rst/legacy/memory_allocation/index.rst
@@ -0,0 +1,52 @@
+.. _mozilla_projects_nss_memory_allocation:
+
+NSS Memory allocation
+=====================
+
+.. container::
+
+   NSS makes extensive use of NSPR's PLArenaPools for memory allocation.
+
+   Each block of memory allocated in a PLArenaPool is called a PLArena. When a PLArenaPool is freed,
+   all the arenas in that pool are put on an arena free list. When NSS attempts to allocate more
+   memory for an arena pool, the PLArenaPool code attempts to use an arena from its free list, and
+   only gets a new arena from the heap if there are no arenas in the free list that are large enough
+   to satisfy the request.
+
+   There are two consequences of the use of PLArenaPools that affect leak analysis. They are:
+
+   1. At the end of execution of a program, all the arenas in the free list will appear to have been
+   leaked. This makes it difficult to tell arenas that are truly leaked from those that are merely
+   in the free list.
+
+   There is a function named PL_ArenaFinish that really frees all the arenas on the free list. See
+   the prototype at
+   `http://mxr.mozilla.org/nspr/source/n.../ds/plarenas.h <http://mxr.mozilla.org/nspr/source/nsprpub/lib/ds/plarenas.h>`__
+
+   A program should call that function at the very end, after having shutdown NSS and NSPR, to
+   really free the contents of the free list. After that function returns, any arenas that still
+   appear to be leaked have truly been leaked, and are not merely on the free list.
+
+   2. Leak analysis tools will frequently report the wrong call stack for the allocation of leaked
+   arenas.
+
+   When the arena free list is in use, the first user of an arena will allocate it from the heap,
+   but will then free it to the free list. The second user will allocated it from the free list and
+   return it to the free list. If and when an arena is leaked, the developer wants to see the call
+   stack of the most recent allocation of the arena, not the stack of the oldest allocation of that
+   arena. But leak analysis tools only record the allocation of memory from the heap, not memory
+   from the arena free list, so they will always show the first allocation (from the heap) and not
+   the most recent allocation (from the arena free list).
+
+   Consequently, when the arena free list is in use, the allocation call stacks shown will typically
+   NOT be the stack of the code that most recently allocated that arena, but rather will be the
+   stack of the code that FIRST allocated that arena from the heap, and then placed it on the free
+   list.
+
+   To solve that problem, it is generally necessary to disable the arena free list, so that arenas
+   are actually freed back to the heap each time they are freed, and are allocated afresh from the
+   heap each time they are allocated. This makes NSS slower, but produces accurate leak allocation
+   stacks. To accomplish that, set an environment variable prior to the initialization of NSS and
+   NSPR. This can be done outside the program entirely, or can be done by the program itself, in the
+   main() function. Set the environment variable NSS_DISABLE_ARENA_FREE_LIST to have any non-empty
+   value, e.g. NSS_DISABLE_ARENA_FREE_LIST=1.
+\ No newline at end of file