[ltt-dev] [PATCH 08/10 round10] comments for memory management

[laijs@cn.fujitsu.com (Lai Jiangshan)]

Signed-off-by: Lai Jiangshan <laijs at cn.fujitsu.com>
---
 rculfhash.c |   33 +++++++++++++++++++++++++++++++++
 1 files changed, 33 insertions(+), 0 deletions(-)

diff --git a/rculfhash.c b/rculfhash.c
index b764dc1..3f982cf 100644
--- a/rculfhash.c
+++ b/rculfhash.c
@@ -117,6 +117,39 @@
  * grow hash table from order 5 to 6: init the index=6 bucket node table
  * shrink hash table from order 6 to 5: fini the index=6 bucket node table
  *
+ * Bucket memory management:
+ * - Bucket node order tables are high level or algorithm level view
+ *   of bucket management of the hash table. The management of
+ *   the memory where the bucket node tables locate is low level
+ *   or raw level view of the hash table.
+ * - The bucket management uses cds_lfht_alloc_bucket_table(order) and
+ *   cds_lfht_free_bucket_table(order) of the memory management to
+ *   alloc/free the bucket node tables.
+ * - Memory management attributes: min_alloc_size, max_size
+ *   Memory management configurations: LFHT_MEMORY_ORDER, LFHT_MEMORY_CHUNK,
+ *   				       LFHT_MEMORY_RESERVED
+ * - min_alloc_size: the smallest allocation buckets size to use and the
+ *   small bucket node tables are forced to be allocated in this contiguous
+ *   memory which improve cache locality of small index orders.
+ * - max_size: the max size of buckets for future growing.
+ * - LFHT_MEMORY_ORDER: a block order memory per a bucket node order table.
+ *   (except small bucket node tables, see min_alloc_size).
+ *   + the size of the table can grow infinitely
+ *   + two level bucket indexing which requires hard/soft fls()
+ *   + bad indexing when there is node hardware fls() instruction
+ * - LFHT_MEMORY_CHUNK: use same-size memory chunks. A big bucket node table
+ *   will be constructed by multi/one memory chunk(s). The size of a chunk
+ *   is choson to be min_alloc_size.
+ *   + a chunk ptr table need be be allocted when the hash table is created
+ *   + two level bucket indexing but simpler than LFHT_MEMORY_ORDER
+ * - LFHT_MEMORY_RESERVED: reserve a large memory space for all the max_size
+ *   buckets when hash table is created. All of the bucket node tables
+ *   are/(will be) allocated in this contiguous memory space. The memory
+ *   is allocated only when it is demanded. And when a bucket node table
+ *   is free, the memory can be discard to reduce system memory presure.
+ *   + one level bucket indexing, extremly simple
+ *   + recomended only when the system have enough memory space: 64BITS.
+ *
  * A bit of ascii art explanation:
  * 
  * Order index is the off-by-one compare to the actual power of 2 because 
-- 
1.7.4.4