o Introduction to pool for those without psychic powers.

lib/mm/pool.h

@@ -10,6 +10,47 @@
 #include <string.h>
 #include <stdlib.h>
 
+
+/*
+ * The pool allocator is useful when you are going
+ * to allocate lot's of memory, use the memory for
+ * a bit, and then free the memory in one go.  A
+ * surprising amount of code has this usage
+ * profile.
+ *
+ * You should think of the pool as an infinite,
+ * contigous chunk of memory.  The front of this
+ * chunk of memory contains allocated objects, the
+ * second half is free.  pool_alloc grabs the next
+ * 'size' bytes from the free half, in effect
+ * moving it into the allocated half.  This
+ * operation is very efficient.
+ *
+ * pool_free free's the allocated object *and* all
+ * objects allocated after it.  It is important to
+ * note this semantic difference from malloc/free.
+ * This is also extremely efficient, since a
+ * single pool_free can dispose of a large complex
+ * object.
+ *
+ * pool_destroy free's all allocated memory.
+ *
+ * eg, If you are building a binary tree in your
+ * program, and know that you are only ever going
+ * to insert into your tree, and not delete (eg,
+ * maintaining a symbol table for a compiler).
+ * You can create yourself a pool, allocate the
+ * nodes from it, and when the tree becomes
+ * redundant call pool_destroy (no nasty iterating
+ * through the tree to free nodes).
+ *
+ * eg, On the other hand if you wanted to
+ * repeatedly insert and remove objects into the
+ * tree, you would be better off allocating the
+ * nodes from a free list; you cannot free a
+ * single arbitrary node with pool.
+ */
+
 struct pool;
 
 /* constructor and destructor */