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