GHashTable基本用法和注意事项

1. GHashTable API介绍
   Glib中实现了一个高效的哈希表 —— GHashTable，可用来存储和查询键值对，GHashTable的主要 API定义如下：

#include <glib.h>


                    GHashTable;
GHashTable*         g_hash_table_new                    (GHashFunc hash_func,
                                                         GEqualFunc key_equal_func);
                                                         
GHashTable*         g_hash_table_new_full               (GHashFunc hash_func,
                                                         GEqualFunc key_equal_func,
                                                         GDestroyNotify key_destroy_func,
                                                         GDestroyNotify value_destroy_func);
                                                         
guint               (*GHashFunc)                        (gconstpointer key);

gboolean            (*GEqualFunc)                       (gconstpointer a,
                                                         gconstpointer b);
                                                         
void                g_hash_table_insert                 (GHashTable *hash_table,
                                                         gpointer key,
                                                         gpointer value);
                                                         
void                g_hash_table_replace                (GHashTable *hash_table,
                                                         gpointer key,
                                                         gpointer value);
                                                         
guint               g_hash_table_size                   (GHashTable *hash_table);

gpointer            g_hash_table_lookup                 (GHashTable *hash_table,
                                                         gconstpointer key);
                                                         
gboolean            g_hash_table_lookup_extended        (GHashTable *hash_table,
                                                         gconstpointer lookup_key,
                                                         gpointer *orig_key,
                                                         gpointer *value);
                                                         
void                g_hash_table_foreach                (GHashTable *hash_table,
                                                         GHFunc func,
                                                         gpointer user_data);
                                                         
gpointer            g_hash_table_find                   (GHashTable *hash_table,
                                                         GHRFunc predicate,
                                                         gpointer user_data);
                                                         
void                (*GHFunc)                           (gpointer key,
                                                         gpointer value,
                                                         gpointer user_data);
                                                         
gboolean            g_hash_table_remove                 (GHashTable *hash_table,
                                                         gconstpointer key);
                                                         
gboolean            g_hash_table_steal                  (GHashTable *hash_table,
                                                         gconstpointer key);
                                                         
guint               g_hash_table_foreach_remove         (GHashTable *hash_table,
                                                         GHRFunc func,
                                                         gpointer user_data);
                                                         
guint               g_hash_table_foreach_steal          (GHashTable *hash_table,
                                                         GHRFunc func,
                                                         gpointer user_data);
                                                         
void                g_hash_table_remove_all             (GHashTable *hash_table);

void                g_hash_table_steal_all              (GHashTable *hash_table);

GList*              g_hash_table_get_keys               (GHashTable *hash_table);

GList*              g_hash_table_get_values             (GHashTable *hash_table);

gboolean            (*GHRFunc)                          (gpointer key,
                                                         gpointer value,
                                                         gpointer user_data);
                                                         
#define             g_hash_table_freeze                 (hash_table)

#define             g_hash_table_thaw                   (hash_table)

void                g_hash_table_destroy                (GHashTable *hash_table);

GHashTable*         g_hash_table_ref                    (GHashTable *hash_table);

void                g_hash_table_unref                  (GHashTable *hash_table);

                    GHashTableIter;
void                g_hash_table_iter_init              (GHashTableIter *iter,
                                                         GHashTable *hash_table);
                                                         
gboolean            g_hash_table_iter_next              (GHashTableIter *iter,
                                                         gpointer *key,
                                                         gpointer *value);
                                                         
GHashTable*         g_hash_table_iter_get_hash_table    (GHashTableIter *iter);

void                g_hash_table_iter_remove            (GHashTableIter *iter);

void                g_hash_table_iter_steal             (GHashTableIter *iter);

gboolean            g_direct_equal                      (gconstpointer v1,
                                                         gconstpointer v2);
                                                         
guint               g_direct_hash                       (gconstpointer v);

gboolean            g_int_equal                         (gconstpointer v1,
                                                         gconstpointer v2);
                                                         
guint               g_int_hash                          (gconstpointer v);

gboolean            g_str_equal                         (gconstpointer v1,
                                                         gconstpointer v2);
                                                         
guint               g_str_hash                          (gconstpointer v);

在 Glib中， GHashTable结构体是定义在 C文件中的，因此 GHashTable结构体里的具体内容是对用户程序不可见的，用户程序无法直接访问 GHashTable结构体的内容，这也在一定程度上减小了用户直接修改 GHashTable元数据的可能性，有利于程序的稳定性。

2. GHashTable使用示例

#include <glib.h>
#include <stdio.h>
#include <string.h>
#include <stdint.h>

struct card {
	uint64_t id;
	char cardholder[64];
	uint8_t state;
	uint8_t level;
};

static guint hash_func(gconstpointer key)
{
	uint64_t id = *(uint64_t *)key;
	return (guint)((id >> 32) ^ (id & 0xffffffff));
}

static gboolean equal_func(gconstpointer a, gconstpointer b)
{
	uint64_t id1 = *(uint64_t *)a;
	uint64_t id2 = *(uint64_t *)b;

	return id1 == id2;
}

void key_destroy_func(gpointer key)
{
	printf("%s:%d free key: %llu\n", __func__, __LINE__, *(uint64_t *)key);
	g_free(key);
}

void value_destroy_func(gpointer value)
{
	struct card *c = (struct card *)value;
	printf("%s:%d free card: id=%llu, cardholder=%s\n", __func__, __LINE__,
			c->id, c->cardholder);
	g_free(value);
}

int main(void)
{
    //GHashTable t; error: incomplete type 'GHashTable'
	GHashTable *tab = g_hash_table_new_full(hash_func, equal_func,
			key_destroy_func, value_destroy_func);

 	uint64_t *id = g_malloc(sizeof(uint64_t));
	struct card *c = g_malloc(sizeof(struct card));

	c->id = *id = 20241222;
	strncpy(c->cardholder, "zhangsan", sizeof(c->cardholder));
	c->state = 0;
	c->level = 0;
	g_hash_table_insert(tab, id, c);

    uint64_t search = 20241222;
	struct card *target = (struct card*)g_hash_table_lookup(tab, &search);
	printf("cardholder: %s, id=%llu, state=%d, level=%d\n", target->cardholder,
        target->id, target->state, target->level);

	g_hash_table_remove_all(tab);

	g_hash_table_destroy(tab);

	return 0;
}

程序运行结果如下：

$ gcc -o main main.c -I/opt/homebrew/Cellar/glib/2.80.2/include/glib-2.0 -I/opt/homebrew/Cellar/glib/2.80.2/lib/glib-2.0/include -L/opt/homebrew/Cellar/glib/2.80.2/lib/ -lglib-2.0
$ ./main
cardholder: zhangsan, id=20241222, state=0, level=0
key_destroy_func:29 free key: 20241222
value_destroy_func:36 free card: id=20241222, cardholder=zhangsan

3. GHashTable注意事项

1)在调用 g_hash_table_insert()后，key所指向的内存和 value所指向的内存，将由 GHashTable在某个时候释放，比如：在调用 replace、remove、destroy等接口的时候，因此用户程序一定要关注那些可能会导致 GHashTable释放 key、value的操作，避免在 GHashTable将 key、 value释放后，用户程序还在访问 key、value所指向的内存的情况。

2)GHashTable不是多线程安全的，如果用户程序有多个线程需要同时访问 GHashTable，则一定要做好加锁和互斥，确保不要在一个线程正在访问 GHashTable时，另外一个线程更新 GHashTable，这里的访问包括正在查询某一个 value，或正在持有某一个 value，并进行读写，此时的更新操作可能会释放这个 value，所以要做好互斥。