r12338@catbus: nickm | 2007-04-10 20:29:05 -0400

 Document memory pool implementation, and tweak it even mor.  See? Programming is fun.


svn:r9940

1 files changed, 20 insertions, 7 deletions

diff --git a/src/common/mempool.h b/src/common/mempool.h
index 2ee32fb137..a1bc3bd0d1 100644
--- a/src/common/mempool.h
+++ b/src/common/mempool.h
@@ -1,6 +1,6 @@
 /* Copyright 2007 Nick Mathewson */
 /* See LICENSE for licensing information */
-/* $Id: /tor/trunk/src/common/util.c 12153 2007-03-12T03:11:12.797278Z nickm  $ */
+/* $Id$ */
 
 /**
  * \file util.h
@@ -10,25 +10,38 @@
 #ifndef MEMPOOL_H
 #define MEMPOOL_H
 
+/** A memory pool is a context in which a large number of fixed-sized
+* objects can be allocated efficiently.  See mempool.c for implementation
+* details. */
 typedef struct mp_pool_t mp_pool_t;
 
 void *mp_pool_get(mp_pool_t *pool);
 void mp_pool_release(void *item);
 mp_pool_t *mp_pool_new(size_t item_size, unsigned int n_per_chunk);
-void mp_pool_clean(mp_pool_t *pool);
+void mp_pool_clean(mp_pool_t *pool, int n);
 void mp_pool_destroy(mp_pool_t *pool);
 void mp_pool_assert_ok(mp_pool_t *pool);
 
 #ifdef MEMPOOL_PRIVATE
-typedef struct mp_chunk_t mp_chunk_t;
+/* These declarations are only used by mempool.c and test.c */
 
-/** DOCDOC */
 struct mp_pool_t {
-  mp_chunk_t *empty_chunks;
-  mp_chunk_t *used_chunks;
-  mp_chunk_t *full_chunks;
+  /** Doubly-linked list of chunks in which no items have been allocated.
+   * The front of the list is the most recently emptied chunk. */
+  struct mp_chunk_t *empty_chunks;
+  /** Doubly-linked list of chunks in which some items have been allocated,
+   * but which are not yet full. The front of the list is the chunk that has
+   * most recently been modified. */
+  struct mp_chunk_t *used_chunks;
+  /** Doubly-linked list of chunks in which no more items can be allocated.
+   * The front of the list is the chunk that has most recently become full. */
+  struct mp_chunk_t *full_chunks;
+  /** Length of <b>empty_chunks</b>. */
   int n_empty_chunks;
+  /** Size of each chunk (in items). */
   int new_chunk_capacity;
+  /** Size to allocate for each item, including overhead and alignment
+   * padding. */
   size_t item_alloc_size;
 };
 #endif