/* [<][>][^][v][top][bottom][index][help] */
/* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @file cache_hash.h
* @brief Cache Hash Tables
*
* @defgroup Cache_Hash Hash Tables
* @ingroup MOD_CACHE
* @{
*/
#ifndef CACHE_HASH_H
#define CACHE_HASH_H
#ifdef __cplusplus
extern "C" {
#endif
#include "mod_cache.h"
/**
* When passing a key to cache_hash_set or cache_hash_get, this value can be
* passed to indicate a string-valued key, and have cache_hash compute the
* length automatically.
*
* @remark cache_hash will use strlen(key) for the length. The null-terminator
* is not included in the hash value (why throw a constant in?).
* Since the hash table merely references the provided key (rather
* than copying it), cache_hash_this() will return the null-term'd key.
*/
#define CACHE_HASH_KEY_STRING (-1)
/**
* Abstract type for hash tables.
*/
typedef struct cache_hash_t cache_hash_t;
/**
* Abstract type for scanning hash tables.
*/
typedef struct cache_hash_index_t cache_hash_index_t;
/**
* Create a hash table.
* @param size
* @return The hash table just created
*/
cache_hash_t* cache_hash_make(apr_size_t size);
/**
* Create a hash table.
* @param *ht Pointer to the hash table to be freed.
* @return void
* @remark The caller should ensure that all objects have been removed
* from the cache prior to calling cache_hash_free(). Objects
* not removed from the cache prior to calling cache_hash_free()
* will be unaccessable.
*/
void cache_hash_free(cache_hash_t *ht);
/**
* Associate a value with a key in a hash table.
* @param ht The hash table
* @param key Pointer to the key
* @param klen Length of the key. Can be CACHE_HASH_KEY_STRING to use the string length.
* @param val Value to associate with the key
* @remark If the value is NULL the hash entry is deleted.
* @return The value of the deleted cache entry (so the caller can clean it up).
*/
void* cache_hash_set(cache_hash_t *ht, const void *key,
apr_ssize_t klen, const void *val);
/**
* Look up the value associated with a key in a hash table.
* @param ht The hash table
* @param key Pointer to the key
* @param klen Length of the key. Can be CACHE_HASH_KEY_STRING to use the string length.
* @return Returns NULL if the key is not present.
*/
void* cache_hash_get(cache_hash_t *ht, const void *key,
apr_ssize_t klen);
/**
* Start iterating over the entries in a hash table.
* @param ht The hash table
* @example
*/
/**
* <PRE>
*
* int sum_values(cache_hash_t *ht)
* {
* cache_hash_index_t *hi;
* void *val;
* int sum = 0;
* for (hi = cache_hash_first(ht); hi; hi = cache_hash_next(hi)) {
* cache_hash_this(hi, NULL, NULL, &val);
* sum += *(int *)val;
* }
* return sum;
* }
*
* There is no restriction on adding or deleting hash entries during an
* iteration (although the results may be unpredictable unless all you do
* is delete the current entry) and multiple iterations can be in
* progress at the same time.
* </PRE>
*/
cache_hash_index_t* cache_hash_first(cache_hash_t *ht);
/**
* Continue iterating over the entries in a hash table.
* @param hi The iteration state
* @return a pointer to the updated iteration state. NULL if there are no more
* entries.
*/
cache_hash_index_t* cache_hash_next(cache_hash_index_t *hi);
/**
* Get the current entry's details from the iteration state.
* @param hi The iteration state
* @param key Return pointer for the pointer to the key.
* @param klen Return pointer for the key length.
* @param val Return pointer for the associated value.
* @remark The return pointers should point to a variable that will be set to the
* corresponding data, or they may be NULL if the data isn't interesting.
*/
void cache_hash_this(cache_hash_index_t *hi, const void **key,
apr_ssize_t *klen, void **val);
/**
* Get the number of key/value pairs in the hash table.
* @param ht The hash table
* @return The number of key/value pairs in the hash table.
*/
int cache_hash_count(cache_hash_t *ht);
/** @} */
#ifdef __cplusplus
}
#endif
#endif /* !CACHE_HASH_H */