crccache/rmm_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  * A hash table allocated&maintained in an RMM memory structure, so it can be used
  17  * in shared memory
  18  *
  19  * Based on apr_hash.h
  20  *
  21  *  Created on: 02/08/2010
  22  *      Author: Alex Wulms
  23  */
  24
  25 #ifndef RMM_HASH_H_
  26 #define RMM_HASH_H_
  27
  28 #include <apr_general.h>
  29 #include <apr_rmm.h>
  30 #include <apr_hash.h>
  31
  32 #define RMM_OFF_NULL 0
  33
  34 #define RMM_OFF_T_DECLARE(type) typedef apr_rmm_off_t rmm_##type##_rmm_off_t
  35 #define RMM_OFF_T(type) rmm_##type##_rmm_off_t
  36
  37 RMM_OFF_T_DECLARE(rmm_hash_index_t);
  38 RMM_OFF_T_DECLARE(rmm_hash_t);
  39
  40 #define APR_RMM_ADDR_GET(type, rmm, offset) ((type *)apr_rmm_addr_get(rmm, offset))
  41
  42 /**
  43  * Create a hash table
  44  * @param rmm: the relocatable memory (structure) in which the hash table must be created
  45  * @return: the offset of the table in the rmm or RMM_OFF_NULL if the table can not be allocated
  46  */
  47 APR_DECLARE(RMM_OFF_T(rmm_hash_t)) rmm_hash_make(apr_rmm_t *rmm);
  48
  49 /**
  50  * Create a hash table with a custom hash functon
  51  * @param rmm: the relocatable memory (structure) in which the hash table must be created
  52  * @param hash_func: the custom hash function
  53  * @return: the offset of the table in the rmm or RMM_OFF_NULL if the table can not be allocated
  54  */
  55 APR_DECLARE(RMM_OFF_T(rmm_hash_t)) rmm_hash_make_custom(apr_rmm_t *rmm,
  56                                                apr_hashfunc_t hash_func);
  57
  58 /**
  59  * Associate a value with a key in a hash table
  60  * @param rmm The relocatable memory structure in which the hash table exists
  61  * @param ht The (offset of the) hash table in the rmm
  62  * @param key The (offset of the) key in the rmm. The key must exist in the same rmm as the hash table.
  63  *            The key will not be copied into the hash table. In stead, a reference to the key will
  64  *            be stored.
  65  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length. See apr_hash.h for
  66  *   furher details (rmm_hash uses same hash function as apr_hash)
  67  * @param val The (offset of the) value in the rmm. Like the key, the rmm must exist in the same rmm as
  68  *            the hash table.
  69  * @return NULL if the key is new. Otherwise the (RMM offset of the) old value. It is the responsability of the
  70  *            invoking application to free the old value from the RMM memory if it is no longer required
  71  * @remark When value RMM_OFF_NULL is passed, the hash entry itself is deleted but not the key nor the value
  72  */
  73 APR_DECLARE(apr_rmm_off_t) rmm_hash_set(apr_rmm_t *rmm, RMM_OFF_T(rmm_hash_t) ht,
  74                                apr_rmm_off_t key,
  75                                apr_ssize_t klen,
  76                                apr_rmm_off_t val);
  77
  78
  79 /**
  80  * Look up the value associated with a key in a hash table.
  81  * @param rmm The relocatable memory structure in which the hash table exists
  82  * @param ht The (offset of the) hash table in the rmm
  83  * @param key A pointer to the key in the (local) address space of the caller.
  84  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length. See apr_hash.h for
  85  *   furher details (rmm_hash uses same hash function as apr_hash)
  86  * @return Returns NULL if the key is not present.
  87  */
  88
  89 APR_DECLARE(apr_rmm_off_t) rmm_hash_get(apr_rmm_t *rmm, RMM_OFF_T(rmm_hash_t) ht,
  90                                  const void *key,
  91                                  apr_ssize_t klen);
  92
  93 /**
  94  * Start iterating over the entries in a hash table.
  95  * @param allocate_hi If false, an internal non-thread-safe iterator is used
  96  *                    Otherwise, a new iterator is allocated from the rmm
  97  * @param rmm The relocatable memory structure in which the hash table exists
  98  *            and/or from which to allocate the RMM_OFF_T(rmm_hash_index_t) iterator.
  99  * @param ht  The (offset of the) hash table in the rmm
 100  * @return The (offset of the) hash index/iterator
 101  * @remark  There is no restriction on adding or deleting hash entries during
 102  * an iteration (although the results may be unpredictable unless all you do
 103  * is delete the current entry) and multiple iterations can be in
 104  * progress at the same time.
 105  */
 106 /**
 107  * @example
 108  *
 109  * <PRE>
 110  *
 111  * int sum_values(apr_rmm_t *rmm, RMM_OFF_T(rmm_hash_t) ht)
 112  * {
 113  *     RMM_OFF_T(rmm_hash_index_t) hi;
 114  *     apr_rmm_off_t val;
 115  *     int sum = 0;
 116  *     for (hi = rmm_hash_first(0, rmm, ht); hi; hi = rmm_hash_next(rmm, hi)) {
 117  *         rmm_hash_this(rmm, hi, NULL, NULL, &val);
 118  *         sum += *(APR_RMM_ADDR_GET(int, rmm, val));
 119  *     }
 120  *     return sum;
 121  * }
 122  * </PRE>
 123  */
 124 APR_DECLARE(RMM_OFF_T(rmm_hash_index_t)) rmm_hash_first(int allocate_hi, apr_rmm_t *rmm, RMM_OFF_T(rmm_hash_t) ht);
 125
 126 /**
 127  * Continue iterating over the entries in a hash table.
 128  * @param rmm The relocatable memory structure in which the hash table exists
 129  * @param hi The iteration state
 130  * @return the RMM offset of the updated iteration state.  RMM_OFF_NULL if there are no more
 131  *         entries.
 132  */
 133 APR_DECLARE(RMM_OFF_T(rmm_hash_index_t)) rmm_hash_next(apr_rmm_t *rmm, RMM_OFF_T(rmm_hash_index_t)hi);
 134
 135
 136 /**
 137  * Get the current entry's details from the iteration state.
 138  * @param rmm The relocatable memory structure in which the hash table exists
 139  * @param hi The iteration state
 140  * @param key Return pointer for the RMM offset of the key.
 141  * @param klen Return pointer for the key length.
 142  * @param val Return pointer for the RMM offset of the associated value.
 143  * @remark The return pointers should point to a variable that will be set to the
 144  *         corresponding data, or they may be NULL if the data isn't interesting.
 145  */
 146 APR_DECLARE(void) rmm_hash_this(apr_rmm_t *rmm, RMM_OFF_T(rmm_hash_index_t) hi,
 147                                                                 apr_rmm_off_t *key,
 148                                 apr_ssize_t *klen,
 149                                 apr_rmm_off_t *val);
 150
 151 /**
 152  * Get the number of key/value pairs in the hash table.
 153  * @param rmm The relocatable memory structure in which the hash table exists
 154  * @param ht The hash table
 155  * @return The number of key/value pairs in the hash table.
 156  */
 157 APR_DECLARE(unsigned int) rmm_hash_count(apr_rmm_t *rmm, RMM_OFF_T(rmm_hash_t) ht);
 158
 159 /**
 160  * Clear any key/value pairs in the hash table.
 161  * @param rmm The relocatable memory structure in which the hash table exists
 162  * @param free_keys If true, free the memory in the RMM used by the keys
 163  * @param free_values If true, free the memory in the RMM used by the values
 164  * @param ht The hash table
 165  */
 166
 167 APR_DECLARE(void) rmm_hash_clear(apr_rmm_t *rmm, int free_keys, int free_values, RMM_OFF_T(rmm_hash_t) ht);
 168
 169 #endif /* RMM_HASH_H_ */