Divide 01a-memory.md into doxygen.

1 files changed, 20 insertions, 0 deletions

diff --git a/src/lib/memarea/lib_memarea.dox b/src/lib/memarea/lib_memarea.dox
index 9a7c8c4b2f..041191482d 100644
--- a/src/lib/memarea/lib_memarea.dox
+++ b/src/lib/memarea/lib_memarea.dox
@@ -7,4 +7,24 @@ once.  This kind of allocation is very fast and avoids fragmentation, at the
 expense of requiring all the data to be freed at the same time.  We use this
 for parsing and diff calculations.
 
+It's often handy to allocate a large number of tiny objects, all of which
+need to disappear at the same time.  You can do this in tor using the
+memarea.c abstraction, which uses a set of grow-only buffers for allocation,
+and only supports a single "free" operation at the end.
+
+Using memareas also helps you avoid memory fragmentation.  You see, some libc
+malloc implementations perform badly on the case where a large number of
+small temporary objects are allocated at the same time as a few long-lived
+objects of similar size.  But if you use tor_malloc() for the long-lived ones
+and a memarea for the temporary object, the malloc implementation is likelier
+to do better.
+
+To create a new memarea, use `memarea_new()`.  To drop all the storage from a
+memarea, and invalidate its pointers, use `memarea_drop_all()`.
+
+The allocation functions `memarea_alloc()`, `memarea_alloc_zero()`,
+`memarea_memdup()`, `memarea_strdup()`, and `memarea_strndup()` are analogous
+to the similarly-named malloc() functions.  There is intentionally no
+`memarea_free()` or `memarea_realloc()`.
+
 **/