From: Pavel Charvat <pchar@ucw.cz>
Date: Sun, 7 Nov 2010 13:39:46 +0000 (+0100)
Subject: hashtable: Updated docs.
X-Git-Tag: v5.0~133
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=fd34e95ac659477f8c5bfeecd9ff9f69e24ec646;p=libucw.git

hashtable: Updated docs.
---

diff --git a/ucw/doc/hashtable.txt b/ucw/doc/hashtable.txt
index 13af5a81..2d0375a9 100644
--- a/ucw/doc/hashtable.txt
+++ b/ucw/doc/hashtable.txt
@@ -80,9 +80,15 @@ to customize the behaviour. The macros are:
 - `HASH_GIVE_ALLOC` -- you need to provide `void
   \*HASH_PREFIX(alloc)(uns size` and `void HASH_PREFIX(free)(void \*)`
   to allocate and deallocate the nodes. Default uses
-  <<memory:xmalloc()>> and <<memory:xfree()>> or <<mempool:,mempool
-  routines>>, depending on <<use_pool,`HASH_USE_POOL`>> and
-  <<auto_pool,`HASH_AUTO_POOL>> switches.
+  <<memory:xmalloc()>> and <<memory:xfree()>>, <<mempool:mempool
+  routines>> or <<eltpool:eltpool routines>>, depending on
+  <<use_pool,`HASH_USE_POOL`>>, <<auto_pool,`HASH_AUTO_POOL`>>,
+  <<use_eltpool,`HASH_USE_ELTPOOL`>> and <<auto_eltpool,`HASH_AUTO_ELTPOOL`>> switches.
+- <<table_alloc:`HASH_GIVE_TABLE_ALLOC`>> -- you need to provide `void
+  \*HASH_PREFIX(table_alloc)(uns size` and `void HASH_PREFIX(table_free)(void \*)`
+  to allocate and deallocate the table itself. Default uses
+  <<memory:xmalloc()>> and <<memory:xfree()>> or the functions
+  from `HASH_GIVE_ALLOC` depending on <<table_alloc:`HASH_TABLE_ALLOC`>> switch.
 
 [[params]]
 Optional parameters
@@ -106,15 +112,27 @@ You can customize the hash table a little more by these macros:
 [[auto_pool]]
 - `HASH_AUTO_POOL` -- like above, but it creates it's own mempool.
   Define it to the block size of the pool.
+[[use_eltpool]]
+- `HASH_USE_ELTPOOL` -- tells to use <<eltpool:,eltpool allocation>> to
+  allocate the nodes. You should define it to the name of eltpool
+  variable to be used for this purpose.
+[[auto_eltpool]]
+- `HASH_AUTO_ELTPOOL` -- like above, but it creates it's own mempool.
+  Define it to the number of preallocated nodes in each chunk of memory.
 - `HASH_ZERO_FILL` -- initialize new nodes to all zeroes.
+[[table-alloc]]
 - `HASH_TABLE_ALLOC` -- allocate the table the same way as nodes. If
   not provided, <<mempory:xmalloc()>> is used.
+- `HASH_TABLE_GROWING` -- never decrease the size of allocated table of nodes.
 [[table_dynamic]]
 - `HASH_TABLE_DYNAMIC` -- By default, only one global hash table is
   used. With this macro defined, all functions gain new first
   parameter of type `HASH_PREFIX(table) *` to allow them work with
   multiple hash tables.
-- `HASH_TABLE_VARS` -- extra variables to be defined in `HASH_PREFIX(table) *`.
+- `HASH_TABLE_VARS` -- extra variables to be defined at head
+  of `HASH_PREFIX(table) *` structure. It can be useful in combination
+  with <<table_dynamic:`HASH_TABLE_DYNAMIC`>> to access per-table custom variables
+  from macros or function switches before you include the generator.
 
 [[wants]]
 Functionality switches
diff --git a/ucw/hashtable.h b/ucw/hashtable.h
index 099ee7bd..96c41afa 100644
--- a/ucw/hashtable.h
+++ b/ucw/hashtable.h
@@ -3,6 +3,7 @@
  *
  *	(c) 2002--2004 Martin Mares <mj@ucw.cz>
  *	(c) 2002--2005 Robert Spalek <robert@ucw.cz>
+ *	(c) 2010 Pavel Charvat <pchar@ucw.cz>
  *
  *	This software may be freely distributed and used according to the terms
  *	of the GNU Lesser General Public License.
@@ -97,9 +98,7 @@
  *			will leak pool memory.
  *  HASH_AUTO_POOL=size	Create a pool of the given block size automatically.
  *  HASH_USE_ELTPOOL=pool Allocate all nodes from given eltpool.
- *			Only works for nodes of limited size.
  *  HASH_AUTO_ELTPOOL=count Create an eltpool of the given number of elements in each chunk.
- *			Only works for fixed-sized nodes and zero HASH_GIVE_EXTRA_SIZE.
  *  HASH_ZERO_FILL	New entries should be initialized to all zeroes.
  *  HASH_TABLE_ALLOC	The hash table itself will be allocated and freed using
  *			the same allocation functions as the nodes instead of
@@ -162,6 +161,9 @@ typedef struct P(bucket) {
 } P(bucket);
 
 struct P(table) {
+#ifdef HASH_TABLE_VARS
+  HASH_TABLE_VARS
+#endif
   uns hash_size;
   uns hash_count, hash_max, hash_min, hash_hard_max;
   P(bucket) **ht;
@@ -171,9 +173,6 @@ struct P(table) {
 #ifdef HASH_AUTO_ELTPOOL
   struct eltpool *eltpool;
 #endif
-#ifdef HASH_TABLE_VARS
-  HASH_TABLE_VARS
-#endif
 };
 
 #ifdef HASH_TABLE_DYNAMIC
@@ -366,9 +365,6 @@ static inline void P(cleanup_alloc) (TAU) { }
 
 #elif defined(HASH_AUTO_ELTPOOL)
 /* Use our own eltpools */
-#ifdef HASH_GIVE_EXTRA_SIZE
-#error HASH_AUTO_ELTPOOL not supported in combination with variable-sized nodes
-#endif
 #include "ucw/eltpool.h"
 static inline void * P(alloc) (TAUC unsigned int size UNUSED) { return ep_alloc(T.eltpool); }
 static inline void P(free) (TAUC void *x) { ep_free(T.eltpool, x); }
@@ -385,6 +381,10 @@ static inline void P(cleanup_alloc) (TAU) { }
 
 #endif
 
+#if defined(HASH_USE_ELTPOOL) && defined(HASH_GIVE_EXTRA_SIZE)
+#error Eltpools not supported in combination with variable-sized nodes
+#endif
+
 #ifdef HASH_GIVE_TABLE_ALLOC
 /* If the caller has requested to use his own allocation functions, do so */
 #elif defined(HASH_TABLE_ALLOC)