forked from osmocom/wireshark
246 lines
7.5 KiB
C
246 lines
7.5 KiB
C
/** @file
|
|
* Definitions for the Wireshark Memory Manager Hash Map
|
|
* Copyright 2014, Evan Huus <eapache@gmail.com>
|
|
*
|
|
* Wireshark - Network traffic analyzer
|
|
* By Gerald Combs <gerald@wireshark.org>
|
|
* Copyright 1998 Gerald Combs
|
|
*
|
|
* SPDX-License-Identifier: GPL-2.0-or-later
|
|
*/
|
|
|
|
#ifndef __WMEM_MAP_H__
|
|
#define __WMEM_MAP_H__
|
|
|
|
#include <glib.h>
|
|
|
|
#include "wmem_core.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif /* __cplusplus */
|
|
|
|
/** @addtogroup wmem
|
|
* @{
|
|
* @defgroup wmem-map Hash Map
|
|
*
|
|
* A hash map implementation on top of wmem. Provides insertion, deletion and
|
|
* lookup in expected amortized constant time. Uses universal hashing to map
|
|
* keys into buckets, and provides a generic strong hash function that makes
|
|
* it secure against algorithmic complexity attacks, and suitable for use
|
|
* even with untrusted data.
|
|
*
|
|
* @{
|
|
*/
|
|
|
|
struct _wmem_map_t;
|
|
typedef struct _wmem_map_t wmem_map_t;
|
|
|
|
/** Creates a map with the given allocator scope. When the scope is emptied,
|
|
* the map is fully destroyed. Items stored in it will not be freed unless they
|
|
* were allocated from the same scope. For details on the GHashFunc and
|
|
* GEqualFunc parameters, see the glib documentation at:
|
|
* https://developer-old.gnome.org/glib/stable/glib-Hash-Tables.html
|
|
*
|
|
* If the keys are coming from untrusted data, do *not* use glib's default hash
|
|
* functions for strings, int64s or doubles. Wmem provides stronger equivalents
|
|
* below. Feel free to use the g_direct_hash, g_int_hash, and any of the
|
|
* g_*_equal functions though, as they should be safe.
|
|
*
|
|
* @param allocator The allocator scope with which to create the map.
|
|
* @param hash_func The hash function used to place inserted keys.
|
|
* @param eql_func The equality function used to compare inserted keys.
|
|
* @return The newly-allocated map.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
wmem_map_t *
|
|
wmem_map_new(wmem_allocator_t *allocator,
|
|
GHashFunc hash_func, GEqualFunc eql_func)
|
|
G_GNUC_MALLOC;
|
|
|
|
/** Creates a map with two allocator scopes. The base structure lives in the
|
|
* metadata scope, and the map data lives in the data scope. Every time free_all
|
|
* occurs in the data scope the map is transparently emptied without affecting
|
|
* the location of the base / metadata structure.
|
|
*
|
|
* WARNING: None of the map (even the part in the metadata scope) can be used
|
|
* after the data scope has been *destroyed*.
|
|
*
|
|
* The primary use for this function is to create maps that reset for each new
|
|
* capture file that is loaded. This can be done by specifying wmem_epan_scope()
|
|
* as the metadata scope and wmem_file_scope() as the data scope.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
wmem_map_t *
|
|
wmem_map_new_autoreset(wmem_allocator_t *metadata_scope, wmem_allocator_t *data_scope,
|
|
GHashFunc hash_func, GEqualFunc eql_func)
|
|
G_GNUC_MALLOC;
|
|
|
|
/** Inserts a value into the map.
|
|
*
|
|
* @param map The map to insert into.
|
|
* @param key The key to insert by.
|
|
* @param value The value to insert.
|
|
* @return The previous value stored at this key if any, or NULL.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
void *
|
|
wmem_map_insert(wmem_map_t *map, const void *key, void *value);
|
|
|
|
/** Check if a value is in the map.
|
|
*
|
|
* @param map The map to search in.
|
|
* @param key The key to lookup.
|
|
* @return true if the key is in the map, otherwise false.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
gboolean
|
|
wmem_map_contains(wmem_map_t *map, const void *key);
|
|
|
|
/** Lookup a value in the map.
|
|
*
|
|
* @param map The map to search in.
|
|
* @param key The key to lookup.
|
|
* @return The value stored at the key if any, or NULL.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
void *
|
|
wmem_map_lookup(wmem_map_t *map, const void *key);
|
|
|
|
/** Lookup a value in the map, returning the key, value, and a boolean which
|
|
* is true if the key is found.
|
|
*
|
|
* @param map The map to search in.
|
|
* @param key The key to lookup.
|
|
* @param orig_key (optional) The key that was determined to be a match, if any.
|
|
* @param value (optional) The value stored at the key, if any.
|
|
* @return true if the key is in the map, otherwise false.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
gboolean
|
|
wmem_map_lookup_extended(wmem_map_t *map, const void *key, const void **orig_key, void **value);
|
|
|
|
/** Remove a value from the map. If no value is stored at that key, nothing
|
|
* happens.
|
|
*
|
|
* @param map The map to remove from.
|
|
* @param key The key of the value to remove.
|
|
* @return The (removed) value stored at the key if any, or NULL.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
void *
|
|
wmem_map_remove(wmem_map_t *map, const void *key);
|
|
|
|
/** Remove a key and value from the map but does not destroy (free) them. If no
|
|
* value is stored at that key, nothing happens.
|
|
*
|
|
* @param map The map to remove from.
|
|
* @param key The key of the value to remove.
|
|
* @return TRUE if key is found FALSE if not.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
gboolean
|
|
wmem_map_steal(wmem_map_t *map, const void *key);
|
|
|
|
/** Retrieves a list of keys inside the map
|
|
*
|
|
* @param list_allocator The allocator scope for the returned list.
|
|
* @param map The map to extract keys from
|
|
* @return list of keys in the map
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
wmem_list_t*
|
|
wmem_map_get_keys(wmem_allocator_t *list_allocator, wmem_map_t *map);
|
|
|
|
/** Run a function against all key/value pairs in the map. The order
|
|
* of the calls is unpredictable, since it is based on the internal
|
|
* storage of data.
|
|
*
|
|
* @param map The map to use
|
|
* @param foreach_func the function to call for each key/value pair
|
|
* @param user_data user data to pass to the function
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
void
|
|
wmem_map_foreach(wmem_map_t *map, GHFunc foreach_func, gpointer user_data);
|
|
|
|
/** Run a function against all key/value pairs in the map. If the
|
|
* function returns TRUE, then the key/value pair is removed from
|
|
* the map. The order of the calls is unpredictable, since it is
|
|
* based on the internal storage of data.
|
|
*
|
|
* @param map The map to use
|
|
* @param foreach_func the function to call for each key/value pair
|
|
* @param user_data user data to pass to the function
|
|
* @return The number of items removed
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
guint
|
|
wmem_map_foreach_remove(wmem_map_t *map, GHRFunc foreach_func, gpointer user_data);
|
|
|
|
/** Return the number of elements of the map.
|
|
*
|
|
* @param map The map to use
|
|
* @return the number of elements
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
guint
|
|
wmem_map_size(wmem_map_t *map);
|
|
|
|
/** Compute a strong hash value for an arbitrary sequence of bytes. Use of this
|
|
* hash value should be secure against algorithmic complexity attacks, even for
|
|
* short keys. The computation uses a random seed which is generated on wmem
|
|
* initialization, so the same key will hash to different values on different
|
|
* runs of the application.
|
|
*
|
|
* @param buf The buffer of bytes (does not have to be aligned).
|
|
* @param len The length of buf to use for the hash computation.
|
|
* @return The hash value.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
guint32
|
|
wmem_strong_hash(const guint8 *buf, const size_t len);
|
|
|
|
/** An implementation of GHashFunc using wmem_strong_hash. Prefer this over
|
|
* g_str_hash when the data comes from an untrusted source.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
guint
|
|
wmem_str_hash(gconstpointer key);
|
|
|
|
/** An implementation of GHashFunc using wmem_strong_hash. Prefer this over
|
|
* g_int64_hash when the data comes from an untrusted source.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
guint
|
|
wmem_int64_hash(gconstpointer key);
|
|
|
|
/** An implementation of GHashFunc using wmem_strong_hash. Prefer this over
|
|
* g_double_hash when the data comes from an untrusted source.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
guint
|
|
wmem_double_hash(gconstpointer key);
|
|
|
|
/** @}
|
|
* @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* __cplusplus */
|
|
|
|
#endif /* __WMEM_MAP_H__ */
|
|
|
|
/*
|
|
* Editor modelines - https://www.wireshark.org/tools/modelines.html
|
|
*
|
|
* Local variables:
|
|
* c-basic-offset: 4
|
|
* tab-width: 8
|
|
* indent-tabs-mode: nil
|
|
* End:
|
|
*
|
|
* vi: set shiftwidth=4 tabstop=8 expandtab:
|
|
* :indentSize=4:tabSize=8:noTabs=true:
|
|
*/
|