rubbos/app/httpd-2.0.64/modules/experimental/cache_hash.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef CACHE_HASH_H
  18 #define CACHE_HASH_H
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 #include "mod_cache.h"
  25
  26 /**
  27  * @file cache_hash.h
  28  * @brief Cache Hash Tables
  29  */
  30
  31 /**
  32  * @defgroup Cache_Hash  Hash Tables
  33  * @ingroup CACHE
  34  * @{
  35  */
  36
  37 /**
  38  * When passing a key to cache_hash_set or cache_hash_get, this value can be
  39  * passed to indicate a string-valued key, and have cache_hash compute the
  40  * length automatically.
  41  *
  42  * @remark cache_hash will use strlen(key) for the length. The null-terminator
  43  *         is not included in the hash value (why throw a constant in?).
  44  *         Since the hash table merely references the provided key (rather
  45  *         than copying it), cache_hash_this() will return the null-term'd key.
  46  */
  47 #define CACHE_HASH_KEY_STRING     (-1)
  48
  49 /**
  50  * Abstract type for hash tables.
  51  */
  52 typedef struct cache_hash_t cache_hash_t;
  53
  54 /**
  55  * Abstract type for scanning hash tables.
  56  */
  57 typedef struct cache_hash_index_t cache_hash_index_t;
  58
  59 /**
  60  * Create a hash table.
  61  * @param size
  62  * @return The hash table just created
  63   */
  64 CACHE_DECLARE(cache_hash_t *) cache_hash_make(apr_size_t size);
  65
  66 /**
  67  * Create a hash table.
  68  * @param *ht Pointer to the hash table to be freed.
  69  * @return void
  70  * @remark The caller should ensure that all objects have been removed
  71  *         from the cache prior to calling cache_hash_free(). Objects
  72  *         not removed from the cache prior to calling cache_hash_free()
  73  *         will be unaccessable.
  74  */
  75 CACHE_DECLARE(void) cache_hash_free(cache_hash_t *ht);
  76
  77
  78 /**
  79  * Associate a value with a key in a hash table.
  80  * @param ht The hash table
  81  * @param key Pointer to the key
  82  * @param klen Length of the key. Can be CACHE_HASH_KEY_STRING to use the string length.
  83  * @param val Value to associate with the key
  84  * @remark If the value is NULL the hash entry is deleted.
  85  * @return The value of the deleted cache entry (so the caller can clean it up).
  86  */
  87 CACHE_DECLARE(void *) cache_hash_set(cache_hash_t *ht, const void *key,
  88                                      apr_ssize_t klen, const void *val);
  89
  90 /**
  91  * Look up the value associated with a key in a hash table.
  92  * @param ht The hash table
  93  * @param key Pointer to the key
  94  * @param klen Length of the key. Can be CACHE_HASH_KEY_STRING to use the string length.
  95  * @return Returns NULL if the key is not present.
  96  */
  97 CACHE_DECLARE(void *) cache_hash_get(cache_hash_t *ht, const void *key,
  98                                    apr_ssize_t klen);
  99
 100 /**
 101  * Start iterating over the entries in a hash table.
 102  * @param ht The hash table
 103  * @example
 104  */
 105 /**
 106  * <PRE>
 107  *
 108  *     int sum_values(cache_hash_t *ht)
 109  *     {
 110  *         cache_hash_index_t *hi;
 111  *         void *val;
 112  *         int sum = 0;
 113  *         for (hi = cache_hash_first(ht); hi; hi = cache_hash_next(hi)) {
 114  *             cache_hash_this(hi, NULL, NULL, &val);
 115  *             sum += *(int *)val;
 116  *         }
 117  *         return sum;
 118  *     }
 119  *
 120  * There is no restriction on adding or deleting hash entries during an
 121  * iteration (although the results may be unpredictable unless all you do
 122  * is delete the current entry) and multiple iterations can be in
 123  * progress at the same time.
 124  * </PRE>
 125   */
 126 CACHE_DECLARE(cache_hash_index_t *) cache_hash_first(cache_hash_t *ht);
 127
 128 /**
 129  * Continue iterating over the entries in a hash table.
 130  * @param hi The iteration state
 131  * @return a pointer to the updated iteration state.  NULL if there are no more
 132  *         entries.
 133  */
 134 CACHE_DECLARE(cache_hash_index_t *) cache_hash_next(cache_hash_index_t *hi);
 135
 136 /**
 137  * Get the current entry's details from the iteration state.
 138  * @param hi The iteration state
 139  * @param key Return pointer for the pointer to the key.
 140  * @param klen Return pointer for the key length.
 141  * @param val Return pointer for the associated value.
 142  * @remark The return pointers should point to a variable that will be set to the
 143  *         corresponding data, or they may be NULL if the data isn't interesting.
 144  */
 145 CACHE_DECLARE(void) cache_hash_this(cache_hash_index_t *hi, const void **key,
 146                                   apr_ssize_t *klen, void **val);
 147
 148 /**
 149  * Get the number of key/value pairs in the hash table.
 150  * @param ht The hash table
 151  * @return The number of key/value pairs in the hash table.
 152  */
 153 CACHE_DECLARE(int) cache_hash_count(cache_hash_t *ht);
 154
 155
 156 /** @} */
 157 #ifdef __cplusplus
 158 }
 159 #endif
 160
 161 #endif  /* !CACHE_HASH_H */