Question

The documentation for g_hash_table_new() indicates

Hash values are used to determine where keys are stored within the GHashTable data structure.

but how are the hash values used?

It seems g_hash_table_foreach() traverses the table from 0 to N- 1 for N nodes. I used this function to print out the hash, key, and value for each node:

test.c

#include <glib.h>

static GHashTable* _htab = NULL;

static int VALS[] = { 1, 2, 3, 4, 5 };

struct kv {
  gpointer key;
  gpointer val;
};

static struct kv KEYVALS[] = {
  { "aaa",    &VALS[0] },
  { "a",      &VALS[1] },
  { "b",      &VALS[2] },
  { "bbbbbb", &VALS[3] },
  { "aaaaa",  &VALS[4] }
};

static void iter(gpointer key, gpointer val, gpointer data) {
  g_printf("key=%s(%p) val=%d(%p) hash=%u\n",
      (char*)key, key,
      *(int*)val, val,
      g_str_hash((char*)key)
  );
}

int main(int argc, char* argv[]) {
  int i;

  if (!_htab) {
    _htab = g_hash_table_new(g_str_hash, g_str_equal);
    g_assert(_htab);
  }

  for (i = 0; i < sizeof(KEYVALS) / sizeof(KEYVALS[0]); i++) {
    g_hash_table_insert(_htab, KEYVALS[i].key, KEYVALS[i].val);
  }
  g_hash_table_foreach(_htab, iter, NULL);
  g_hash_table_remove_all(_htab);
  g_hash_table_destroy(_htab);
  return 0;
}

The output is always the same (other than the pointer values) even after multiple runs, so there’s some kind of algorithm used here. How does a node’s hash (e.g., from g_str_hash()) determine where it’s stored in the GHashTable?

$ gcc `pkg-config --cflags glib-2.0` `pkg-config --libs glib-2.0` test.c
$ ./a.out
key=bbbbbb(0x10f142ee0) val=4(0x10f1430ac) hash=4087176913
key=a(0x10f142edc) val=2(0x10f1430a4) hash=177670
key=b(0x10f142ede) val=3(0x10f1430a8) hash=177671
key=aaaaa(0x10f142ee7) val=5(0x10f1430b0) hash=252781386
key=aaa(0x10f142ed8) val=1(0x10f1430a0) hash=193485928
$

Answer 1

Let’s see what the source code might tell us.

static inline guint
g_hash_table_lookup_node (GHashTable    *hash_table,
                          gconstpointer  key,
                          guint         *hash_return)
{
  /* ... */
  hash_value = hash_table->hash_func (key);
  /* ... */
  node_index = hash_value % hash_table->mod;
  /* ... */

The hash value is taken modulo some value. Let’s see what it might be.

static void
g_hash_table_set_shift (GHashTable *hash_table, gint shift)
{
  /* ... */
  hash_table->size = 1 << shift;
  hash_table->mod  = prime_mod [shift];
  /* ... */

Aha, a prime number from a static const array of predefined primes. But where is it set?

#define HASH_TABLE_MIN_SHIFT 3  /* 1 << 3 == 8 buckets */

/* ... */

GHashTable *
g_hash_table_new_full (GHashFunc      hash_func,
                       GEqualFunc     key_equal_func,
                       GDestroyNotify key_destroy_func,
                       GDestroyNotify value_destroy_func)
{
  /* ... */
  hash_table = g_slice_new (GHashTable);
  g_hash_table_set_shift (hash_table, HASH_TABLE_MIN_SHIFT);

and

static void
g_hash_table_resize (GHashTable *hash_table)
{
  /* ... */
  g_hash_table_set_shift_from_size (hash_table, hash_table->nnodes * 2);

So on GHashTable’s creation a certain prime number is assigned to it and it’s used to translate a hash value to an index. Afterwards, when the hash table grows, g_hash_table_set_shift is called once again to update the prime value and causes different indices to be returned for given hash values.